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Novell SecureLogin Application Definition Guide 


About This Guide 


This guide helps users to write or modify application definitions for single sign-on-enabled 
applications. Most users will find it quicker and easier to use the Application Definition Wizard but, 
assuming the relevant permissions have been granted, users may also write their own application 
definitions to suit their particular requirements. 

* Chapter 2, “Command Quick Reference,” on page 13 

¢ Chapter 1, “Application Definition Language: an Overview,” on page 9 

+ Chapter 3, “Managing Application Definitions,” on page 25 

* Chapter 4, “Application definition variables,” on page 43 

+ Chapter 5, “Command Reference,” on page 53 

+ Chapter 6, “Testing Application Definitions,” on page 173 

+ Chapter 7, “Reference Commands and Keys,” on page 179 

+ Chapter 8, “Application Definition Commands for SNMP Alerts,” on page 187 


Audience 
This guide is intended for: 


¢ System and network administrators 
* System integrators 


+ IT Support staff 


Feedback 


We want to hear your comments and suggestions about this manual and the other documentation 
included with this product. Please use the User Comments feature at the bottom of each page of the 
online documentation, or go to www.novell.com/documentation/feedback.html and enter your 
comments there. 


Documentation Updates 

For the most recent version of the Application Definition Guide, visit the Novell SecureLogin 
Documentation Web site (http://www.novell.com/documentation/securelogin70). 
Additional Documentation 


For documentation on other Novell SecureLogin documentation, see the Novell SecureLogin 
Documentation Web site (http://www.novell.com/documentation/securelogin70). 


The other documents available with this release of Novell SecureLogin are: 


* Getting Started 


* Novell SecureLogin Readme 
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+ Novell SecureLogin Quick Start Guide 
+ Novell SecureLogin Overview Guide 
¢ Installation 
+ Novell SecureLogin Installation Guide 
¢ Administration 
+ Novell SecureLogin Administration Guide 
+ Novell SecureLogin Application Definition Wizard Administration Guide 
+ Novell SecureLogin Citrix and Terminal Services Guide 
+ pcProx Guide 
* End User 
+ Novell SecureLogin User Guide 


Documentation Conventions 


In Novell documentation, a greater-than symbol (>) is used to separate actions within a step and 
items in a cross-reference path. 


When a single pathname can be written with a backslash for some platforms or a forward slash for 
other platforms, the pathname is presented with a backslash. Users of platforms that require a 
forward slash, such as Linux or UNIX, should use forward slashes as required by your software. 


Novell SecureLogin Application Definition Guide 


1.1 


1.2 


Application Definition Language: an 
Overview 


The capability of Novell SecureLogin to create proprietary application definitions is a powerful 
feature. This application definition command language facilitates single sign-on of all types of 
applications. 


SecureLogin implements application definition commands to provide a flexible single sign-on and 
monitoring environment. For example, the SecureLogin Windows Agent watches for application 
login boxes. When a login box is identified, the agent runs an application definition to enter the 
username, password, and background authentication information. 


This section contains the following information: 


+ Section 1.1, “What is an Application Definition?,” on page 9 

+ Section 1.2, “Advantages of Using Application Definitions,” on page 9 

+ Section 1.3, “Using Application Definitions,” on page 10 

* Section 1.4, “Defining Applications Enabled for Single Sign-On,” on page 10 
+ Section 1.5, “Corporate Definitions,” on page 10 

+ Section 1.6, “Using Dialog Specifier Commands,” on page 11 

+ Section 1.7, “Reading from and Writing to Variables,” on page 11 


What is an Application Definition? 


An application definition is essentially a list of instructions that SecureLogin follows in order to 
perform various tasks on various windows. For example, for a Windows application )* . exe), an 
application definition is written for each executable file that you want SecureLogin to act upon. In 
that application definition, you are able to assign different instructions to each dialog box or screen 
that the executable file or application might produce. By doing this, you have the choice of acting 
upon only the login panel, only selected windows, or every window that is produced by the 
executable file, such as account locked, invalid username, invalid password, back-end database is 
down, password expiry, and so on. 


SecureLogin follows the application definition from left to right, top to bottom. However, with the 
use of flow control commands, such as 6811, it is possible to skip, repeat, or jump to certain parts of 
the application definition. 


Advantages of Using Application Definitions 


¢ Enables you to single sign-on enable almost any Windows, mainframe, internet, intranet, 
terminal server, or Unix application. 
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1.3 


1.4 


1.5 


+ No need to install software on your application servers. 


¢ The flexibility for you and your application owners to choose what to do once an application 
generated message is detected, giving you full control over your single sign-on environment. 


+ Allows more sophisticated single sign-on to supported applications, including the ability to 
seamlessly handle several versions of one application. This feature is especially important when 
you upgrade your applications. 


* Security. Novell SecureLogin data (for example, user credentials) is stored and protected in the 
directory. 


+ Speed. When Novell SecureLogin is started, it locates user data in the directory and caches its 
encrypted contents in memory (and optionally on disk) for later use by the workstation's Novell 
SecureLogin agent. 


Using Application Definitions 
You can use application definitions to: 


+ Execute the retrieval and entering of correct login details. Application definitions are stored and 
secured within the directory to ensure maximum security, support for single-point 
administration, and manageability. 


+ Automate many login processes, such as multi-page login and login panels requiring other 
information that you can store in the directory (such as surname or telephone number). 


¢ Application definitions can include commands to automate password changes on behalf of users 
and to request user input when required. 


* Application definitions can accommodate error handling that is generated by the back-end 
application. For example, handling of invalid logins. 


Defining Applications Enabled for Single Sign-On 


Novell SecureLogin provides the option to define which applications are enabled for single sign-on. 
This option gives you: 


+ Complete control for deciding which applications need to be enabled for single sign-on. 


¢ The ability to update the entire directory database with a new application login application 
definition by updating a single object. 


Corporate Definitions 


Corporate applications allow scripts to flow down to all users located within a container, allowing 
central administrators and maintenance of the script. 


Corporate application definitions are stored in a container object rather than on the individual user 
objects. For users, the result is a less complex system. 


For you as the administrator, the improved login mechanisms provide the following: 


+ A greater level of accountability with increased productivity and security. 


* Areduced workload at the help desk because of significantly fewer password resets. 
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1.6 


1.7 


1.7.1 


Using Dialog Specifier Commands 


Using the Dialog Specifier commands, you can assign individual sections of an application 
definition to the different windows an executable file produces. This allows the login dialog box, for 
example, to be treated differently from the Error Message box and so on. 


Currently, there are 65 different commands in the Novell SecureLogin application definition 
language. Many of the SecureLogin commands such as Repeat and Dialog, have one or two 
commands that are used to close them. 


Reading from and Writing to Variables 


Application definition commands can read from and write to variables. These variables enable 
SecureLogin to use corporate application definitions, while each individual user's secrets are securely 
stored in the directory. It is also possible to read attributes, such as the user's full name and phone 
number, from attributes in the directory. 


SecureLogin not only writes information to the screen, but also reads from it with the use of 
commands such as ReadText. Use this to extract usernames, domains in use, error messages, and 
other useful information. Use Variable Manipulator commands to perform calculations, break 
apart information, and join it back together again. 


All these features come together to form an extremely powerful language that is able to accomplish 
almost any task that is required. 


Using Characters Interpretable by Novell SecureLogin 


Using interpretable characters in Novell SecureLogin application definitions has implications for 
definitions that are created in, or copied from, and pasted from a Microsoft Word. 


For example, when you are writing an application definition that requires a “-” (dash) in the 
command syntax, make sure you use a short "—" or en dash (Unicode glyph U+2013 (Hex) or 
8211(Decimal) and cannot be an extended "—" or em dash as generated in Microsoft Word. 


In Microsoft Word, when you type a space and one or two hyphens between text, Microsoft Word 
automatically inserts an ASCII dash or en dash ( - ). If you type two hyphens and do not include a 
space before the hyphens, an em dash ( — ) is created. 


Similarly, when you are writing an application definition that requires quotation mark in the 
command syntax, make sure you use a straight quotation mark (Unicode glyph U+0022 (Hex) or 0034 
(Decimal) or the ASCII printable character 34). For quotation mark syntax example, see Section 4.3.7, 
“Quotation Marks,” on page 49. 


In Microsoft Word, when you type a question mark, Word automatically changes straight quotation 
marks to curly (or smart) quotes, as you type unless the Word AutoCorrect, AutoFormat As You Type 
features are disabled. 
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2.1 


Command Quick Reference 


+ Section 2.1, “Application Definition Command Quick Reference,” on page 13 


Application Definition Command Quick Reference 


Table 2-1 Application Definition Command Quick Reference 


Command What it means? 

# Use the this symbol to define a line of text as a comment field. Comment 
fields are used to leave notes. 
For more information, see "א"‎ on page 41 

¡da Use quotation marks to group together text or variables containing spaces. 
Quotation marks are used with commands like Type, MessageBox, and If 
-Text. 
For more information, see "" "” on page 41 

$ Use the dollar sign to define the use of a SecureLogin variable stored in the 
directory for later use by that user. 
For more information, see “$” on page 13 

2 Use the question mark to define the use of a runtime variable. 
The values of these variables are not stored in the directory. They are reset 
each time SecureLogin is started. 
For more information, see “?” on page 41 

% Use the percentage sign to define the use of a directory attribute. The 
attributes that are available vary depending on the directory in use, and the 
setup of the directory. 
For more information, see “%” on page 42 

\ Use the backslash with the Type and Send Key commands to specify the 
use of a special function. 

@ Use this symbol in the same way as the backslash symbol, except its use is 


limited to HLLAPI enabled emulators. 


For more information, see “@” on page 42 


Use the hyphen as a switch within several commands, such as If and 
Type. 


For more information, see "-" on page 42 
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14 


Command 


AAVerify 


What it means? 


It is typically used before the application Username and Password are 
retrieved and entered into the login box. 


For more information, Section 5.2.1, “AAVerify,” on page 59 


Add 


Adds one number to another. The numbers can be hard-coded into the 
application definition, or they can be variables. The result can be the output 
of another variable, or one of the original numbers. 


For more information, see Section 5.2.2, “Add,” on page 62 


Attribute 


Use the Attribute specifier in conjunction with the Tag/EndTag 
command to specify which HTML attributes and attribute values must exist 
for that particular HTML tag. 


For more information, see Section 5.2.3, “Attribute,” on page 64 


AuditEvent 


Use the AuditEvent to audit the following events from an application 
definition: 

* SecureLogin client started 

+ SecureLogin client exited 

+ SecureLogin client activated by user 

* SecureLogin client deactivated by user 

* Password provided to an application by a script 


+ Password changed by the user in response to a changepassword 
command 


+ Password changed automatically in response to a changepassword 
command 


For more information, see Section 5.2.4, “AuditEvent,” on page 65 


BeginSplashScreen/ 
EndSplashScreen 


Use to display a Novell splash screen across the whole Terminal Emulator 
window. This is used to mask any flashing produced by SecureLogin 
scraping the screen for text. A Delay command at the start of the 
application definition ensures that the emulator window is in place before the 
splash screen is displayed. 


For more information, see Section 5.2.5, “BeginSplashScreen/ 
EndSplashScreen,” on page 66 


BooleanInput 


Use BooleanInput within a site block to set the state of a Boolean field 
(either a check box or radio button). 


For more information, see Section 5.2.6, “BooleanInput,” on page 66 


Break Use Break within the Repeat /EndRepeat commands to break out of a 
repeat loop. 
For more information, see Section 5.2.7, “Break,” on page 67 

Call Use the Call command to call and run a subroutine. When a subroutine is 


called, the application definition begins executing from the first line of the 
subroutine. 


For more information, see Section 5.2.8, “Call,” on page 68 
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Command 


ChangePassword 


What it means? 


Use the ChangePassword command to change a single variable and is 
used in scenarios where password expiry is an issue. Set the <Variable> 
to the new password. 


For more information, see Section 5.2.9, “ChangePassword,” on page 69 


Class 


When a window is created, it is based on a template known as a window 
class. The Class command checks to see if the class of the newly created 
window matches its <window-Class> argument. 


For more information, see Section 5.2.10, “Class,” on page 70 


ClearPlat 


ClearSite 


Use to reset the last chosen platform, causing subsequent calls to 
ReLoadPlat to do nothing. 


For more information, see Section 5.2.11, “ClearPlat,” on page 71 
Use within a Site block to clear the ‘matched’ status for a given site. 


For more information, see Section 5.2.12, “ClearSite,” on page 73 


Click 


When used with windows applications, the Click command sends a click 
instruction to the specified <4#Ctr1-ID>. 


For more information, see Section 5.2.13, “Click,” on page 74 


ConvertTime 


Ctrl 


Use to convert a numeric time value, for example, ?CurrTime(system), 
into a legible format and store itin <String Time>. 


For more information, see Section 5.2.14, “ConvertTime,” on page 77 


Use the Ctr1 command to determine if a window contains the control 
expressed in the <#Ctr1-ID> argument. The control ID number is a 
constant that is established at the time a program is compiled. 


For more information, see Section 5.2.15, “Ctrl,” on page 78 


DebugPrint 


Use the DebugPrint command to display the text specified in the <Data> 
variable on a Debug console.The command can take any number of text 
arguments, including variables, (forexample, DebugPrint "The user " 
$Username " has just been logged onto the system"). 


For more information, see Section 5.2.16, “DebugPrint,” on page 78 


Decrement 


Use the Decrement command to subtract from a specified variable. For 
example, you can use Decrement to count the number of passes a 
particular application definition has made. 


For more information, see Section 5.2.17, “Decrement,” on page 79 


Delay 


Use the Delay command to delay the execution of the application definition 
for the time specified in the <Time Period> argument. 


For more information, see Section 5.2.18, “Delay,” on page 80 


Dialog/EndDialog 


Use the Dialog/EndDialog command to identify the beginning and end of 
a dialog specification block respectively. You can use these commands to 
construct a dialog specification block, which consists of a series of dialog 
specification statements (for example Ctrl and Title). 


For more information, see Section 5.2.19, “Dialog/EndDialog,” on page 81 
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Command 


DisplayVariables 


What it means? 


Use the DisplayVariables command to display a dialog box that lists 
the user's stored variables (for example, $Username and $Password) for the 
current application. 


For more information, see Section 5.2.20, “DisplayVariables,” on page 82 


Divide 


Use to divide one number by another. The numbers can be hard coded into 
the application definition, or they can be variables. The result can be output 
to another variable, or to one of the original numbers. 


For more information, see Section 5.2.21, “Divide,” on page 84 


DumpPage 


Use the DumpPage command to provide information about the current Web 
page. Use for debugging Web page application definitions. 


For more information, see Section 5.2.22, “DumpPage,” on page 85 


EndScript 


Event/Event Specifiers 


Use the EndScript command to immediately terminate execution of the 
application definition. 


For more information, see Section 5.2.23, “EndScript,” on page 85 


Application definitions generally execute at the point when an application 
window is created. This corresponds to the WM_CREATE message received 
from an application window at startup. 


By adding the Event Specifier to a dialog block, you can override this 
behavior whereby application definition executes only when the specified 
message is generated. If an Event Specifier is not givem, it is treated as the 
same as Event WM_CREATE. 


For more information, see Section 5.2.24, “Event/Event Specifiers,” on 
page 86 


FocusInput 


GenerateOTP 


Use within a Site Block to focus on an input field based on the Boolean 
value of “focus”. 


For more information, see Section 5.2.25, “FocusInput,” on page 86 


Used to generate a one time password (OTP) as an authentication method 
in lieu of a traditional fixed and static password. 


For more information, see Section 5.2.26, “GenerateOTP,” on page 87 


GetCheckBoxState 


Use the GetCheckBoxState command to return the current state of the 
specified checkbooks. 


For more information, see Section 5.2.27, “GetCheckBoxState,” on page 91 


GetCommandLine 


Use the GetCommandLine command to capture the full command line of 
the program that is loaded, and save it to the specified variable. 


For more information, see Section 5.2.28, “GetCommandLine,” on page 91 


GetEnv 


GetHandle 


Use the GetEnv command to read the value of an environment variable and 
save it in the specified <variable>. 


For more information, see Section 5.2.29, “GetEnv,” on page 92 


Use GetHandle to capture the unique handle of the window on which the 
Windows application definition script is activated. 


For more information, see Section 5.2.30, “GetHandle,” on page 92 
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Command What it means? 

GetIni Use the Get Ini command to read data from the INT file. 
For more information, see Section 5.2.31, “GetIni,” on page 93 

GetMD5 Use the GetMD5 command to generate an MD5 hash value of the current 
process the script is running for. GetMD5 works only with the Win32 scripts. 
For more information, see Section 5.2.32, “GetMD5,” on page 93 

GetReg Use the GetReg command to read data from the registry and save it in the 


specified <variable>. 


For more information, see Section 5.2.33, “GetReg,” on page 95 


GetDirectoryStatus 


Use the GetDirectoryStatus command to find out whether Novell 
SecureLogin can connect to the directory or not. 


For more information, see Section 5.2.34, “GetDirectoryStatus,” on page 96 


GetSessionName 


GetText 


GetURL 


Use the GetSessionName command to find the current HLLAPI session 
name that is used to connect and return it to the specified variable. 


For more information, see Section 5.2.35, “GetSessionName,” on page 96 


Use the GetText command to get all of the text from the screen and save it 
to the specified variable. It is used in a large Web application definition that 
might contain several If -Text statements. 


For more information, see Section 5.2.36, “GetText,” on page 97 


Use the GetURL command to capture the URL of the site that is loaded and 
save it to the specified variable. 


For more information, see Section 5.2.37, “GetURL,” on page 98 


GoToURL 


Use the GOTOURL command to make the browser navigate to the specified 
<URL>. By default the command opens the new Web page in the main 
window, rather than the frame that started the application definition. 


For more information, see Section 5.2.38, “GoTOURL,” on page 98 


If/Else/Endlf 


Use the If command to establish a block to execute if the expression 
supplied is true. The Else command works inside an If block. The Else 
command is executed if the operator in the If block is false. Use the EndIf 
command to terminate the If block. 


For more information, see Section 5.2.40, “If/Else/Endlf,” on page 99 


Include 


Use the Include command to share commonly used application definition 
commands by multiple applications. The application definition identified by 
<Platform-Name> is included at execution time into the calling application 
definition. The application definition included with the Include command 
must consists of commands supported by the calling application. 


For more information, see Section 5.2.41, “Include,” on page 104 


Increment 


Use the Increment command to add to a specified variable. For example, 
you can use increment to count the number of passes a particular 
application definition has made. 


For more information, see Section 5.2.42, “Increment,” on page 104 
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Command 


KillApp 


What it means? 


Use to terminate an application. 


For more information, see Section 5.2.43, “KillApp,” on page 105 


Local 


Use the Local command to declare that a runtime variable will only exist for 
the lifetime of the application definition. Local runtime variables are used in 
the same way as normal runtime variables and are still written as 
Variable. 


For more information, see Section 5.2.44, “Local,” on page 107 


MatchDomain 


Use MatchDomain inside a site block to filter a site based on its domain. If 
the domain does not match, the site block fails to match. 


For more information, see Section 5.2.45, “MatchDomain,” on page 107 


MatchField 


Use MatchField to filter a form based on the presence of a particular field. 
If the field fails to match and it is not specified as optional, then the parent 
form fails to match. 


For more information, see Section 5.2.46, “MatchField,” on page 108 


MatchForm 


Use MatchForm to filter a site based on the presence of a particular field. If 
the field fails to match and it is not specified as optional, then the site fails to 
match. 


For more information, see Section 5.2.47, “MatchForm,” on page 110. 


MatchOption 


Use the MatchOption command to filter a field based on the presence of a 
particular option. 


For more information, see Section 5.2.48, “MatchOption,” on page 111. 


MatchReferer 


Use MatchReferer inside a Site/EndSite block to match or filter a site 
based on a referrer. 


For more information, see Section 5.2.49, “MatchReferer,” on page 112. 


MatchRegex 


Use the MatchRegex command to test whether a regular expression 
matches against the specified string or not. You can also use it inside a Site— 
EndSite or Dialog-EndDialog block for example. 


For more informations, see Section 5.2.50, “MatchRegex,” on page 113. 


MatchTitle 


MatchURL 


Used inside a site block, MatchTitle is used to filter a site based on its 
title. If the site title does not match, the site block fails to match. 


For more information, see Section 5.2.51, “MatchTitle,” on page 114. 


Use MatchURL inside a site block to match or filter an HTML page within a 
site based on its URL. The URL can be a complex Web address or a secure 
Web site. 


For more information, see Section 5.2.52, “MatchURL,” on page 115. 
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Command 


MessageBox 


What it means? 


Use the MessageBox command to display a dialog box that contains the 
text specified in the <Data> variable. The application definition is 
suspended until the user reacts to this message. The MessageBox can take 
any number of text arguments, including variables, (for example 
MessageBox "The user " $Username " has just been logged onto the 
system"). 


For more information, see Section 5.2.53, “MessageBox,” on page 116. 


Multiply 


Use to multiply one number by another. You can hard-code the numbers into 
the application definition, or you can use variables. The results can be 
output to another variable, or to one of the original numbers. 


For more information, see Section 5.2.54, “Multiply,” on page 118. 


OnException/ 
ClearException 


Parent/EndParent 


PickListAdd 


Use the OnException command to detect when certain conditions are met. 
Currently, this is when Cancel is clicked on either of two dialog boxes. When 
the condition is met, a subroutine is run. Use the ClearException 
command to reset the exceptions value. 


For more information, see Section 5.2.55, “OnException/ClearException,” 
on page 119. 


Use the EndParent command to terminate a Parent block and set the 
subject of the application definition back to the original window. You can nest 
the Parent command, thereby allowing the Parent block to act on the 
parent of the parent. 


For more information, see Section 5.2.56, “Parent/EndParent,” on page 125. 


Use the PickList command to allow users with multiple accounts for a 
particular system to choose the account to which they will log in. 


For more information, see Section 5.2.57, “PickListAdd,” on page 126. 


PickListDisplay 


Use the PickListDisplay command to display the pick list entries built by 
previous calls to PickListAdd. The PickListDisplay command returns 
the result in a <?Variable> sent to the command. 


For more information, see Section 5.2.58, “PickListDisplay,” on page 128. 


PositionCharacter 


Use the PositionCharacter command in a password policy application 
definition to enforce that a certain character in the password is a numeral, 
uppercase, lowercase, or a punctuation character. 


For more information, see Section 5.2.59, “PositionCharacter,” on page 129. 


PressInput 


Used within a site block to simulate a keyboard enter event. 


For more information, see Section 5.2.60, “PressInput,” on page 130. 


ReadText 


Use the ReadText command to run in both Windows and Terminal 
Launcher application definitions. Although the usage and arguments for the 
use of ReadText with Windows and Terminal Launcher are different, the 
results of each command are the same. 


For more information, see Section 5.2.61, “ReadText,” on page 130. 


Command Quick Reference 


19 


20 


Command 


RegSplit 


What it means? 


Use the RegSplit command to split a string by using a regular expression. 
<Output-String1> and <Output -String2> contain the first and 
second subexpressions. 


For more information, see Section 5.2.62, “RegSplit,” on page 133. 


ReLoadPlat 


Use to set the current platform to the last one chosen by the application 
definition, or if a platform is not chosen, leaves the platform unset. 


For more information, see Section 5.2.63, “ReLoadPlat,” on page 134. 


Repeat/EndRepeat 


Use the Repeat command to establish an application definition block similar 
to the If command. The repeat block is terminated by an EndRepeat 
command. Alternatively, you can use the Break or EndScript commands 
to break out of the loop. 


For more information, see Section 5.2.64, “Repeat/EndRepeat,” on 
page 136. 


RestrictVariable 


Use the RestrictVariable command to monitor a <Variable> and 
enforce a specified <Password-Policy> on the <Variable>. Any 
variable specified must match the policy or it is not saved. 


For more information, see Section 5.2.65, “RestrictVariable,” on page 138. 


Run Use the Run command to launch the program specified in <Command> with 
the specified optional [<Arg1> [<Arg2>] ..] arguments. 
For more information, see Section 5.2.66, “Run,” on page 140. 

Select Use the Select command to select entries from a combo box or list box 


control. 


For more information, see Section 5.2.68, “Select,” on page 141. 


SelectListBoxltem 


SelectOption 


Use the SelectListBoxItem command to select entries from a list box. 
For more information, see Section 5.2.69, “SelectListBoxltem,” on page 142. 


Use the SelectOption command to select or deselect options within a list 
box or combo dialog box. 


For more information, see Section 5.2.70, “SelectOption,” on page 143. 


SendEvent 


Use the SendEvent command to broadcast events. 


For more information, see Section 5.2.71, “SendEvent,” on page 143 


SendKey 


Use the SendKey command to work only with Generic and Advanced 
Generic emulators. You can use the SendKey command in the same 
manner as the Type command. Generally, the Type command is the 
preferred command to use. The Type command places the text into the 
clipboard, and then pastes it into the emulator screen. The SendKey 
command enters the text directly into the emulator screen. 


For more information, see Section 5.2.72, “SendKey,” on page 144. 


Set 


Use the Set command to copy the value of <Data> into <Variable>. The 
<Data> can be any text, or another variable, whereas the <Variable> 
must be either a ?Variable or $Variable. 


For more information, see Section 5.2.73, “Set,” on page 145. 
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Command 


SetCheckBox 


What it means? 


Use the SetCheckBox command to select or clear a check box. 


For more information, see Section 5.2.74, “SetCheckBox,” on page 146. 


SetCursor 


Use the SetCursor command to set the cursor to a specified 
<ScreenPosition> or<X Co-ordinate> <Y Co-ordinate>. 


For more information, see Section 5.2.75, “SetCursor,” on page 147. 


SetFocus 


Use the SetFocus command to set the keyboard focus to a specified 
<#Ctrl-ID>. 


For more information, see Section 5.2.76, “SetFocus,” on page 148. 


SetPlat 


SetPlat sets the platform or application from which variables are read and 
saved. 


By default, variables are stored directly against the platform or application on 
which you have SecureLogin enabled. For example, if you enable 
Groupwise. exe, the Groupwise credentials are stored against the 
Groupwise. exe platform. SetPlat sets the platform or application from 
which variables are read and saved. 


For more information, see Section 5.2.77, “SetPlat,” on page 149. 


SetPrompt 


Use the SetPrompt command to customize the text in the Enter 
SecureLogin Variables dialog boxes. These dialog boxes are used to prompt 
the user for new variables. You can also use the DisplayVariables 
command to customize the prompt text in the dialog box (for previously 
stored variables). 


For more information, see Section 5.2.78, “SetPrompt,” on page 151. 


Site/Endsite 


Site/Endsite are Web commands added to allow for finer control of site 
matching. More detailed information within a loaded Web site can now be 
matched upon an used to execute blocks of scripting commands. 


Begins and ends an application definition, in place of Dialog/EndDialog. 


For more information, see Section 5.2.80, “Site/Endsite,” on page 153. 


StrCat 


Use the StrCat command to append a second data string to the first data 
string. For example, StrCat ?Result "SecureRemote " 
"$Username". 


For more information, see Section 5.2.81, “StrCat,” on page 155. 


StrLength 


StrLower 


Use the StrLength command to count the number of characters in a 
variable and output that value to the destination variable. 


For more information, see Section 5.2.82, “StrLength,” on page 156. 


Use the StrLower command to modify a variable so that all the characters 
are lowercase. 


For more information, see Section 5.2.83, “StrLower,” on page 156. 


StrUpper 


Use the StrUpper command to modify a variable so that all the characters 
are uppercase. 


For more information, see Section 5.2.84, “StrUpper,” on page 157. 


Command Quick Reference 


21 


22 


Command 


Sub/EndSub 


What it means? 


Use the Sub/EndSub commands around a block of lines within an 
application definition to denote a subroutine. 


For more information, see Section 5.2.85, “Sub/EndSub,” on page 158, 


Submit 


Use the Submit command only in Web application definitions, and only with 
Internet Explorer, to allow for enhanced control of how and when a form is 
submitted. The Submit command performs a Submit on the form in which 
the first password field is found. The Submit command is ignored if used 
with Netscape. 


For more information, see Section 5.2.86, “Submit,” on page 159. 


Substr 


Use the Substr command to search for a sub string from a text based on 
the index and the length which are provided as parameters. 


For more information, see Section 5.2.87, “Substr,” on page 161. 


Subtract 


Use the Subtract command to subtract one value from another. This is 
useful if you are implementing periodic password change functionality for an 
application. You can use the subtract command (in conjunction with the 
Divide function and the Slina DLL) to determine the number of days that 
have elapsed since the last password change. Other numeric commands 
include Add, Divide, and Multiply. 


For more information, see Section 5.2.88, “Subtract,” on page 161. 


Tag/EndTag 


Use the Tag/EndTag commands to find HTML tags. 


For more information, see Section 5.2.89, “Tag/EndTag,” on page 163. 


TextInput 


Use within a site block to input text into a special field. 


For more information, see Section 5.2.90, “TextInput,” on page 163. 


Title 


Use the Title command to retrieve the title of a window and compare it 
against the string specified in the <window-Title> argument. For this 
block of the application definition to run, the retrieved window title and the 
<Window-Title> argument must match the text supplied to the Title 
command in the dialog block. 


For more information, see Section 5.2.91, “Title,” on page 164. 


Type 


Use the Type command to enter data, such as usernames and passwords, 
into applications. There are reserved character sequences that are used to 
type special characters, for example TAB and ENTER. If it is not possible to 
determine Control IDs in a Windows application, and the Type command is 
not working, use the SendKey command instead. 


For more information, see Section 5.2.92, “Type,” on page 165. 


WaitForFocus 


Use the WaitForFocus command to suspend the running of the 
application definition until the <#Ctr1-ID> has received keyboard focus, 
or the <Repeat -Loops> expire. The <Repeat -Loops> is an optional 
value that defines the number of loop cycles to run. The <Repeat -Loops> 
value defaults to 3000 loops if nothing is set. After focus is received, the 
application definition continues. 


For more information, see Section 5.2.93, “WaitForFocus,” on page 170. 
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Command What it means? 


WaitForText Use the WaitForText command so the Terminal Launcher waits for the 
specified <text> to display before continuing. For example, the user waits 
for a username field to display before attempting to type a username. 


For more information, see Section 5.2.94, “WaitForText,” on page 171. 
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3.1 


Managing Application Definitions 


Application definitions are generally imported, built, or modified in the Management utility of 
Novell SecureLogin, tested locally, and then copied to the relevant container, or the organizational 
unit in multi-user directory environments. Application definitions are imported and exported in the 
XML file format for ease of distribution and deployment. 


Novell SecureLogin application definitions can be created using the application definition wizard. 


For more information about the Application Definition Wizard, see the Novell SecureLogin Application 
Definition Wizard Administration Guide . 


Application Definition Checklist 


When you have built or modified your application definitions, it is recommended that you test each 
supported application or the Web page for the following scenarios: 

¢ Entering a correct username or password. 

¢ Entering an incorrect username or password. 

+ Cancelling a login by the user. 

+ Exceeding maximum password retries. 

* A user changing his or her own password. 

+ Attempting to change to an illegal password. 


This illegal password action is relevant when you define a password policy and you try to define 
a password that does not match the policy. 


+ An administrator cancelling a password change. 
+ An administrator changing a user password. 

¢ Expiry of user password. 

¢ Locking out the account. 


* Locking out someone from the account. 
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3.2 Exporting and Importing Predefined Applications and 
Application Definitions 


Novell SecureLogin provides export functionality to facilitate distribution of predefined applications 
and application definitions. Converting predefined applications and application definitions to XML 
format allows you to distribute and deploy predefined applications and application definitions 
across directories, software, and hardware platforms. 


This section contains the following information: 


* Section 3.2.1, “Exporting Individual Applications,” on page 26 
* Section 3.2.2, “Importing Individual Applications,” on page 29 


3.2.1 Exporting Individual Applications 


1 Log in to iManager. 


2 Select Securelogin SSO > Manage Securelogin SSO. The Manage SecureLogin SSO page is 
displayed. 
3 In the object field, specify your object name, then click OK. 


Novell ¡Manager - Mozilla Firefox 


Collection Owner Access 


)4 [ Roles and Tasks 


Y Manage SecureLogin SSO 


[All Categories] 


Directory Administration Specify the object(s) to modify. 
eDirectory Trees Object name: (see list) 
Groups 

Help Desk 


LDAP OK Cancel 


NMAS 


Novell Certificate Access 
Novell Certificate Server 
Novell Secure Workstation 


Partition and licas 


Rights 
Schema 


SecureLogin SSO 
Manage SecureLogin SSO 


Done 


4 Click Distribution. The distribution details are displayed. 
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Manage SecureLogin SSO: 


SecureLogin SSO 
Applications | Logins | Distribution | Password policies | Preferences | Advanced Settings 


Copy Settings 
Load 


Load SecureLogin configuration from an XML file 


Save 


Save SecureLogin configuration to an XML file 
Copy 


Copy SecureLogin configuration to another directory object 


— Ok | Cancel | Apply | 


5 Click Save. The Configuration for Export dialog box is displayed. 


6 Under Select SecureLogin Configuration, select the appropriate text boxes. 


Configuration for Export 
Select SecureLogin Configuration 
applications 

Password Policies 

Passphrase Question 


Preferences 


Configuration Function 

Application Copies, exports, or imports all configured application definitions as 
displayed in the Application pane. 

Credentials Copies, exports, or imports all credentials as displayed in the Logins 
pane, excluding passwords for copy settings and unencrypted export 
or import. 

Password Policies Copies, exports, or imports password policies as displayed in the 


Password Policies Properties table. 
Preferences Copies, exports, or imports preferences manually set in the 
Preferences Properties tables. 


7 Click Export. The Select the Applications for Backup page is displayed. 
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8 Select the applications you want to backup. 


Novell iManager - Mozilla Firefox 


Configuration for Export 


Select SecureLogin Configuration 


Applications 


Password Policies 


passphrase Question Novell iManager - Mozil... 


Preferences Select the Applications for Backup 
C] Select AU 


E web 


O Yahoo! Mail yahoo.co 


9 Click OK. The Save File As dialog box is displayed. 


10 Provide a name to the file, select the file location, and click Save. 


Enter name of file to save to... 


(2 Mozilla Firefox 


chrome 

C components 
My Recent [Cidefaults 
Documents (dictionaries 
(E extensions 
(Soreprefs 

(E plugins 
res 

C searchplugins 
uninstall 
updates 
active-update. xml 
updates. xml 


File name: $so-export.x 
My Network Save as type: Text Document l 


NOTE: The file is saved in an XML format. 
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3.2.2 Importing Individual Applications 


1 Log in to iManager. 

2 Select Securelogin SSO > Manage Securelogin SSO. The Manage SecureLogin SSO page is 
displayed. 

3 In the object field, specify your object name, then click OK. 

4 Click Distribution. The Distribution details are displayed. 


Manage SecureLogin SSO: 


SecureLogin SSO 
Applications | Logins | Distribution | Password policies | Preferences | Advanced Settings 


Copy Settings 


Load 

Load SecureLogin configuration from an XML file 
Save 

Save SecureLogin configuration to an XML file 
Copy 


Copy SecureLogin configuration to another directory object 


5 Click Load. The Select SecureLogin Configuration dialog box is displayed. 


Configuration for Import 


Select SecureLogin Configuration 
Applications 

Password Policies 

Passphrase Question 


Preferences 


Source XAAL file Browse... 
Import Close 


6 Browse to and select the exported XML file. 
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File Upload 


Look in: 


D 


My Recent 
Documents 


5 


Desktop 


My Documents 


3 


My Computer 


6% 


My Network 


O Mozilla Firefox 


v 


(chrome 

(E) components 
(defaults 
(dictionaries 
(extensions 
(areprefs 
(plugins 
res 

C searchplugins 
uninstall 
(updates 

a firefox.exe 
₪ updater.exe 
Fxpideanup.exe 


₪ AccessibleMarshal. dll 


< 


₪ freebl3.dll 

(9) js3250.dl 

₪ nspr4.dll 

B| nss3.dll 

₪ nssckbi.dll 

(3) ples.dll 

(4) plds4.dll 

(3) smime3.dll 

[X] softokn3.dll 
3) ssl3.dll 

₪ xpcorn. dll 

₪ xpcom_compat.dll 
₪ xpcom_core. dl 
(9) xpistub. dll 
,autoreg 


“updater .ini 
LICENSE 

removed-fil 
browsercor 
old-homepe 
[X] Freebl3.chk 
₪ 50/5063 
E install.log 

E install_stati 
El install_wiza 
El README.tx 
active-upde 
8 ]iso-exoort 


updates. xr 


File name: 


Files of type: 


7 Click Open to select the file. 


sso-export.xml 


All Files 


Cancel 


The selected predefined applications and application definitions are copied across to the 
receiving organizational unit or container. 


The selected Securelogin configuration is copied across to the receiving object. 


If predefined applications and application definitions currently exist in the receiving object, a 


confirmation message is displayed to confirm or reject overwrite with the imported data. 


8 Click Import to confirm or click Cancel to reject overwriting with the imported data. 


A SecureLogin message is displayed to confirm SecureLogin data is loaded. 


Configuration for Import 


Operation completed successfully, 


Select SecureLogin Configuration 
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3.3 


Modifying Predefined Applications and Application 
Definitions 


Novell SecureLogin predefined applications and application definitions are easily modified to cater 
to your organization's requirements. 


Use the following procedure to modify a Novell SecureLogin predefined application or application 
definition: 
1 Double-click the SecureLogin icon in the notification area to display the Personal Management 
utility. 
2 Click Applications. The Applications pane is displayed. 
3 Double-click the required application definition. The application details are displayed. 


0 Novell SecureLogin 


5 a Application - "Yahoo messenger" 
5 Generic 

Details iti i 
01-63) Java | Definition | Settings | 
= 8 Startup " 
¡ml Yahoo messenger © Yahoo messenger (Startup) 


₪ ב‎ Terminal Emulator Yahoo messenger [V Enabled 


Credentials 


El NSL Admin 
Username 
Password 


Username writer 
Password EEE 


4 Select the Definition tab. The application definition editor is displayed. 


Cc - 
” Novell SecureLogin. 


= E Applications Application - "Yahoo messenger" 
[A Generic 0 
(3 Java 


> E3 Startup # place your application definition here. 
B Yahoo messenger 


Details D | Settings | 


Ea Terminal Emulator 
f3 Web 
> ב‎ Windows 
+ 8] My Logins 
+ ¿0% Preferences 
{=} Password Policies 


5 Modify the application definition or the predefined application, as required. 
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It is a good practice to include the date and a description of the changes made for future 
reference. 


The predefined Web applications such as eBay or Hotmail under the Type drop-down list are 
titled Web and not Advanced Web. There is no difference between a Web application definition or 
an Advanced Web application definition. 


6 Click OK to save changes and close the Personal Management utility. 


For information on how to modify specific functions see Chapter 5, “Command Reference,” on 
page 53. 
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This section describes how to create and modify SecureLogin application definitions in the Personal 
Management utility. It is recommended that you test the application definitions locally and then copy 
them to the relevant container or organizational unit in multi-user directory environments. 


Use the following procedure to create an application definition for a Windows application: 


1 Double-click the SecureLogin icon in the notification area to display the Personal Management 
utility. 
2 Select File > New > Application. The New Application dialog box is displayed. 


3 Click New Application Definition, and select the required application type from the Type drop- 
down list. 


New Application 


( Predefined Application Definition 


[Windows De | 
Description | 


OK | Cancel | 


4 Specify other details such as the EXE or the description. 
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These fields vary based on the application definition type that you have selected. For example, if 
you select Windows as the Type, you must fill in the EXE and Description fields. 


5 Click OK. The application definition is added to the left pane under applications and the details 
display in the right pane. 


6 Select Definition, and delete the text, ++ place your application definition here. 


Figure 3-1 The Definitions Pane 


Y Novell sso 


E . 
P Novell SecureLogin 


=|} Applications 
E Generic 
[3 Java 
+ {8 Startup # place your application definition here. 
E3 Terminal Emulator 
+ ES Web 
ב‎ Windows 
E) Test 
+ 8] My Logins 
+ ¿0 Preferences 
[2 Password Policies 


7 Specify your application details, then click OK to save the changes and close the Personal 
Management utility. 


NOTE: If you are creating multiple application definitions, click Apply to save changes without 
closing the Personal Management utility. 


Managing Application Definitions 33 


34 


Settings Tab 


Figure 3-2 The Settings Options 


Application - "MSN Hotmail" 


Details | Definition | Settings | 


Allow web page to load while Application Definition is running No 
Enable third party access for this platform No 
Password field must exist on Internet Explorer page for Application Definition to run No 
Prompt for device reauthentication for this application No 
Reauthentication Method Any 
Synchronize with Mobile Device No 


OK | Cancel | Apply 


The Settings tab includes the following options for application definitions and predefined 


applications: 
Table 3-1 Settings Options 


Option 


Allow web page to load while application definition is 
running 


Enable third party access for this platform 
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Description 


Applies to Microsoft Internet Explorer and application 
definitions created for Web pages and JavaScript login 
that execute in a Web page. 


By default, this option is set to No. This suspends 
completion of any other Internet Explorer tasks until 
the log in is completed. 


If this option is set to Yes, Novell SecureLogin allows 
Internet Explorer to continue functioning while Novell 
SecureLogin is executing the login. 


By default, this option is set to No. This disables the 
API access for this predefined application or the 
application definition. 


If this option is set to Yes, it disables the API access 
for this predefined application or application definition. 


3.4 


Option 


Password field must exist on Internet Explorer page for 
application definition to run 


Prompt for device reauthentication for this application 


Reauthentication Method 


Synchronize with Mobile Device 


Description 


Applies to Microsoft Internet Explorer and application 
definitions created for Web pages and JavaScripts 
within Web pages. 


If this option is set to Yes, Novell SecureLogin does 
not execute automated login for pages without a 
password field. 


If this option is set to No, your Web application returns 
errors on pages without password fields that you need 
to handle with Novell SecureLogin. For example, 
password change successful. 


Allows you to reauthenticate an application against an 
Advanced Authentication (AA) device. 


By default, this option is set to No, which means that 
users are not prompted for device reauthentication for 
the application. 


If this option is set to Yes, user are prompted for 
device reauthentication for the application. 


This option allows you to reauthenticate to an 
application before single sign-on. 


This option is available only when Prompt for device 
reauthentication for this application is set to No. 


The reauthentication methods available are: 


+ Any 

+ Biometric 
+ Smart card 
+ Token 

+ Password 
+ Passphrase 


+ Directory password 


This option is set to No by default, enabling 
synchronization to an APl-enabled hand-held device, 
for this predefined application or application definition. 


If this option is set to Yes, it disables synchronization 
to an API-enabled handheld device for this predefined 
application or application definition. 


Windows Application Definition Tools 


Novell SecureLogin provides wizards to assist with the creation of basic application definitions. For 
more complex applications and requirements, Novell SecureLogin provides the following tools to 
assist with finding the application information required to build an application definition: 


+ Section 3.4.1, “Finding Application Details with Window Finder,” on page 36 


* Section 3.4.2, “Finding Application Details with the Login Watcher,” on page 38 
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3.4.1 


Finding Application Details with Window Finder 


The Novell SecureLogin Window Finder finds windows applications details, including control and 
dialog box IDs. Novell SecureLogin might require this information to identify specific objects in 
order to uniquely identify the application. 


Control IDs are used to uniquely identify objects within a window. Window Finder extracts this 
information from the application for use in the application definition. 


+ “Starting the Windows Finder” on page 36 
+ “WINSSO Window Finder Details” on page 37 


Starting the Windows Finder 


The following procedure uses the Novell SecureLogin test application provided on the Novell 
SecureLogin product installer package or your other distribution source. 


1 On the Windows Start menu, select All Programs > Novell Securelogin > Window Finder. The 
Window Finder is displayed. 


36 Novell SecureLogin Application Definition Guide 


2 Right-click the Novell SecureLogin icon in the dialog box, drag it to the required window, 
field or control, and release the mouse button. 


Y winsso Window Finder 


— Module Details 


Module Name: 


Command Line: 


MDS: 


— Parent Details 


Window Title: 


Window Class: 


Handle: 


Control Details 


Dialog ID: 
Class Name: 
Window Text: 


Handle: 


] Show password values 


₪3 Right-click and drag the SecureLogin icon on the left to the Window 
control you want to identify. 


WINSSO Window Finder Details 


The following table lists the fields in the WinSSO Window Finder: 


Table 3-2 Window Finder Details 


Field 


Module Details Section 


Description 


Module Name 


This is the Windows executable name for the selected application. 


This is the application name for a Windows application definition or the 
predefined application. 
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Field Description 


Command Line This is the full command line used to start the application. 


You can use this information in along with the GetCommandLine command. 


Parent Details Section 


Window Title This is the title of the window of the selected control. 


Use with the Title command in the Dialog/EndDialog section of the 
application definition. 


Window Class This is the Windows class name for this dialog or window. 


Use with the Class command in a Dialog or EndDialog section. 


Handle This is the internal Windows handle for this window. 


This is generally not used in application definitions. 


Control Details Section 


Dialog ID This is the unique number identifying the control. 


Use it with various commands, including Type, SetPlat, and Click. 


Class Name This is the Windows class name for the control. 


Novell SecureLogin supported classes, which include Edit, Combo box, and 
Static. 


Window Text This is the test that exists on the control. 
Useful to copy and paste into the application definition editor. 


1. Note or copy the required details from the WinSSO Window Finder 
window from the relevant fields. 


2. Click Close to quit and close the WinSSO Window Finder window. 


3.4.2 Finding Application Details with the Login Watcher 


The Login Watcher records login and Windows application data to provide information that you 
might need for creating an application definition. 


¢ “Order Information Is Recorded and Stored” on page 38 
¢ “Information Details” on page 39 


* “SecureLogin Test Application Example” on page 39 


Order Information Is Recorded and Stored 


Information is recorded and stored in a text file in the following order: 
Time! | Module Name! | Window Handle! | Window Text! | Class Name! | Parent! | Visible Flag | | Title 
Flag! | Control ID 


NOTE: The Login Watcher records all log in information, including usernames and passwords, in a 
text file. This text file might be a security issue. 
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Information Details 


Information Item Description 

Time Milliseconds elapsed since the Login Watcher started. 

Module name Name of the executable being recorded. 

Window handle Unique identifier for the window. 

Window text All text displayed in the window, which includes text entered during login and text 


displayed as labels for fields and buttons. 


Class name Name of the window class. 
Parent Window handle of the parent window. 
Visible flag Refers to top-level windows that have the style set to Visible. 


If set to Visible, the word Visible displays; otherwise the field is empty. 
Title flag Refers to top-level windows that have the style set to display the Window Title. 
If the title is not displayed, then the field is empty. 


Control ID The unique numerical identifier for the windows object. 


SecureLogin Test Application Example 
The following procedure uses the SecureLogin test application: 


1 Right-click the Novell SecureLogin icon on the notification area. 
2 Select close from the menu. 
3 Right-click the Windows Start menu > Explore. 


4 Double-click loginwatch. exe, by default located at <...>\program 
files\novell\securelogin\tools. The Login Watcher dialog box is displayed. 


Y Login Watcher 


Y Login Watcher creates a watch.log file. The 
log file can help you debug SecureLogin 
Application Definitions. 
Type the executable ofthe program that you 
want to watch, then click Start. 


5 Specify the executable filename in the Login Watcher field. For example, YPager.exe. 
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Y Login Watcher 


Login Watcher creates a watch.log file. The 
log file can help you debug SecureLogin 
Application Definitions. 

Type the executable ofthe program that you 
want to watch, then click Start 


[YPager.exe 


Y Login Watcher 


Login Watcher creates a watch.log file. The 
log file can help you debug SecureLogin 
Application Definitions. 

Type the executable ofthe program that you 
wantto watch, then click Start 


[YPager exe 


Close 


7 Log in to the relevant application. 
8 Click Stop when logged on successfully to return to the Login Watcher dialog box. 


9 Click View Log. Novell SecureLogin starts the Notepad application and displays the watch. txt 
file with login details recorded. 


P Watch - Notepad 
File Edit Format View Help 


9406 || YPager.exe || 1182076 
IME || IME || 1706350 || |l 


9500 || YPager.exe || 1706350 
WINDOW || YSOCKET_RECEIVER || 
Title || O 


10 Note the required information or save the text file with a different name. 
11 Click the Login Watcher dialog box. Click Close. 


3.5 Application Definition Elements 


Application definitions use various symbols to define the function of each line. The following table 
lists the definitions for these symbols. 
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Table 3-3 Symbol Definitions 


Symbol 


# 


Description 


Use the number of this symbol to define a line of text as a comment field. Comment fields are 
used to leave notes. 


Any line that starts with a # is ignored. 
Use comment lines for the following: 


+ Defining sections of an application definition, for example the login window and Change 
Password window. 


+ Explaining complex sections. 


+ Removing command lines during creation and editing of the application definition. This 
saves continuously deleting and rewriting lines while testing. 


+ Making notes such as when the application definition was written, what version of the 
software it was written for, and so on. 


When used as part of a command, such as Class or Type, the symbol specifies a numerical 
value. 


You can use these numerical values to specify a target for the command. 


Use quotation marks to group together text or variables that contain spaces. Quotation marks 
are used with commands such as Type, MessageBox, and If -Text. 


For these command lines to work, you must use quotation marks in the following method to 
group the text together: 


+ Type "Database 2" 
+ MessageBox "Please confirm your log in details." 


¢ If -Text "Login failure" 


Use the dollar sign to define the use of a Novell SecureLogin variable stored in the directory 
for later use by that user. 


These variables are used to store information such as usernames and passwords. 


Use the question mark to define the use of a runtime variable. The values of these variables 
are not stored in the directory; they are reset each time Novell SecureLogin is started. 


Alternatively, with the use of the Local command, these variables are reset each time the 
application definition is started. 


These variables are used to store temporary information, such as counting, data processing, 
and date information. The question mark is also used with several internal system generated 
variables. 
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Symbol 


% 


Description 


Use the percentage sign to define the use of a directory attribute. The attributes available 
vary depending on the directory in use, and the setup of the directory. 


Examples of the attributes you can use are FCN and %Surname. 


NOTE: Quotes are required around the variable if the attribute name contains a space. For 
example, 


Set ?text "%Login Time" 

or 

Messagebox "%Given Name" 

For more information, see Section 4.1.2, “Directory Attribute Variables,” on page 44. 


Use the backslash with the Type and SendKey commands to specify the use of a special 
function. 


The backslash is used along with values to perform the simulation of pressing keys. 
Examples of frequently used functions are provided in the following list: 
¢ Alt-F: Alt+F on the keyboard in Windows and Web applications. 


+ 1D: Delete key in a Windows and Web applications. Not applicable to terminal 
emulators. 


+ \N: Enter key in a Windows and Web applications. Not applicable to terminal emulators. 
+ YT: Tab in Windows and Web applications. 
+ YT: Shift+Tab in Windows and Web applications. 


Use the same way as the backslash symbol, except its use is limited to HLLAPI-enabled 
emulators. 


This symbol is used along with values to perform the simulation of key presses. For example, 
use @E to simulate pressing Enter in a terminal emulator application. 


Use the hyphen as a switch within several commands, such as If and Type. 


The hyphen is used along with values to modify the behavior of commands (such as -Raw), 
or switch on or off certain functions (such as -YesNo). 
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Application definition variables 


+ Section 4.1, “Types of Variables,” on page 43 
+ Section 4.2, “Novell SecureLogin Supported Variables,” on page 46 


+ Section 4.3, “Application Definition Best Practices,” on page 47 


4,1 Types of Variables 


Novell SecureLogin supports the use of four different types of variables: 


+ Stored 
¢ Runtime 


¢ Directory attribute 


4.1.1 Using a variable to change the default platform 


NOTE: Specify variables without spaces, for example $Username_Alias. If you use spaces you must 
enclose the entire variable in quotation marks, for example "$Username Alias". 


Each variable defaults to the platform specified in the application definition or the predefined 
application name. You can use a variable to change the platform. 


Example: 
If you have applications A and Z. 


1. Application A has default credential A, and linked credentials B and C. A credential selection 
will prompt you to choose A, B or C. 


2. Application Z has default credential Z with linked credentials W, X and Y If you have set the 
platform to Z and then a credential selection will prompt you to choose W, X, Y or Z. 


$password: This variable will prompt the user for a credential. For application A a credential 
selection will prompt you to choose A, B or C and for application Z a credential selection will prompt 
you to choose W, X, Y or Z. 


$password(A): This variable will not give any choice and will use the credential from A. 


$password(Z): This variable will not give any choice and will use the credential from Z. 
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4.1.2 


4.1.3 


Directory Attribute Variables 


Novell SecureLogin has the ability to read directory attributes from the currently logged on user's 
object. For example: 


Type %CN 
reads the CN attribute from the currently logged in user's object and specifies it. 


You can only use the percentage symbol (%) variables when Novell SecureLogin is configured to use 
a directory, and only on single-valued text attributes. 


Quotes are required around the variable if the attribute name contains a space. For example: 


Set ?text "%Login Time" 
MessageBox "%Given Name" 


For more information on application definition elements and symbol usage refer to Chapter 3, 
“Managing Application Definitions,” on page 25. 


Stored Variables 


Stored variables are the most common style of variable used in application definitions and 
Predefined Applications. They are preceded with a dollar symbol ($). Use these variables to store the 
values used during the login process, such as usernames, passwords and any other details that are 
required. 


This section contains the following information: 


¢ “Storing the Variables” on page 44 
+ “Using Stored Variables” on page 44 


Storing the Variables 


The values of these variables are stored in the directory under the user object. They are encrypted so 
that only the user can access them. You can store variables separately for each application definition 
and predefined application, so the username variable for one application can be different from the 
username variable for another application. It is, however, possible to set an application to read 
variables from another application's application definition and predefined application. This is useful 
for applications that share user accounts or passwords. 


For details on how to do this, see Section 5.2.77, “SetPlat,” on page 149. 


Using Stored Variables 


If a stored variable is referenced in an application definition and predefined application, and there is 
no value stored for that variable (for example, the first time the program is run), SecureLogin 
prompts the user to enter a value for the variable. This is an automatic process. It is also possible to 
manually trigger this process to prompt a user to enter new values for particular variables. 


For details on how to do this, see Section 5.2.20, “Display Variables,” on page 82 and Section 5.2.9, 
“ChangePassword,” on page 69. 
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4.1.4 


NOTE: If you want to hide a variable from an administrator by displaying it as asterix instead 
of clear text, begin the variable name with $Password. For example, the $PasswordPIN variable is 
protected as described, however, $PIN is not. 


(=) 


Example of stored variables in use: 


Dialog 

Class #32770 

Title "Log on" 
EndDialog 

Type $Username #1001 
Type $Password #1002 
Click #1 


Runtime Variables 


Runtime variables are generally used for storage of calculations, processing data, and date 
information. You can also use them for temporary passwords and usernames. 


Runtime variables are preceded by the question mark symbol (?). They have two modes: 


+ Normal runtime variables are reset each time SecureLogin is started. 


¢ Local runtime variables are reset each time the application definition and predefined application 
is started. 


Runtime variables are Normal by default. For details on how to switch a runtime variable to Local 
mode, see Section 5.2.44, “Local,” on page 107. 


Using Runtime Variables 


Runtime variables are not stored in the directory or the Novell SecureLogin cache; they are used 
straight from the computer's memory. For this reason, it is important not to use runtime variables for 
the storage of usernames, passwords, or other details Novell SecureLogin will need to access in the 
future. 


If runtime variables are used for such details, the user is prompted to enter them each time the 
application definition or predefined application is run, or each time Novell SecureLogin is restarted. 
Users are not prompted for ?variables that have no value. These variables are given the value 
<NOTSET>. 


Example of a Runtime Variable 


Dialog 
Class #32770 
Title "ERROR" 
EndDialog 
Local?ErrorCount 
Increment ?ErrorCount 
If?ErrorCount Eq "2" 
MessageBox "This is the second time you have received this error. Would you like to 
reset the application?" -YesNo ?Result 
If ?Result Eq "Yes" 
KillApp "App.exe" 
Run "C:\App\App.exe" 
Else 
Set?ErrorCount "0" 
EndIf 
EndIf 
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4.2 Novell SecureLogin Supported Variables 


Novell SecureLogin reads details from the system and uses them to create variables that you can 
incorporate into the application definition. These variables are automatically generated as runtime 
variables and used in the same manner within any application definition. 


Variable Description 


?BrowserType(system) Contains Internet Explorer and indicates the browser on which the 
application definition is running. 


This variable is only set in a Web application definition. 


?CurrTime(system) Contains the running time in seconds from Jan 1970 to the present. 
Use this variable to force password changes every X days, or similar. 


Do not use the application definition to force a password change if 
you want to continue the application generating the change password 
event. This is recommended. 


Use this variable on applications where you cannot set a password 
expiry at the application back end. 


?DSVariable(system) SecureLogin traps the DataStoreVariableNotAvailable 
exception and stores the name of the variable, which resulted the 
exception, in a built-in variable called 2?DSVariable. This helps in 
tracing errors that occurs while trying to read a directory attribute. 


?SysContext(system) Contains the context within which the current Novell SecureLogin 
user's directory object exists. 


?SysPassword(system) Contains the directory password of the user currently using Novell 
SecureLogin. 


This variable is only available if the appropriate options are chosen 
when installing Novell SecureLogin. 


?SysServer(system) Contains the name of the server or the IP address of the server that 
was entered in the Novell client login panel. 


NOTE: This variable is only available if the Novell client login 
extension is installed (eDirectory) and is not available if the MS Active 
Directory or ADAM option has been installed. 


?SysTree(system) The name of the directory tree that the Novell SecureLogin is 
currently using. 


NOTE: The variable ?SysTree will return the Domain name when 
using Microsoft GINA (Microsoft Active Directory or ADAM) and the 
Tree name or Port Number when using Novell GINA or LDAP 
installation. 


?SysTSLaunched (system) Contains the condition state value when SLLauncher is run. 


This variable is set to "True" when a script is being executed by 
SLLauncher. Otherwise it will be "<NOTSET>". 


?SysUser(system) The name of the user currently using Novell SecureLogin. 
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Variable Description 


?SysVersion(system) The local Novell SecureLogin windows agent version. 


You can use this variable to determine if specific support is built into 
the product running on the user's workstation. Version convention is 
two digits for each section, read from right to left, and leading zeroes 
are removed. For example, version 3.0.4.0 would be returned as 
03000400. 


4.2.1 Variables that enable single sign-on in Firefox 


Novell SecureLogin can select a specific credential set to single sign Firefox authentication dialog 
boxes by adding a Generic application definition called “Firefox—CredentialSelection”. 


IMPORTANT: The application definition of firefox.exe must already exist for adding a generic 
application definition. 


The application definition allows the administrator to define which credentials to use to single sign- 
on to the Firefox authentication dialog box of any realm or domain. The application definition 
contains variables with values that are supplied from the SecureLogin SLoMoz Firefox plug-in. 


Variable Description 


?FFCredential The name of the credential set that the SecureLogin SLoMoz Firefox plug- 
in will use to populate the authentication dialog. By default, the variable will 
store the equivalent of [?FFRealm "2FFDomain"]. 


To allow using ?SysUser and ?SysPassword in a login, set the 
FFCredential to be -SysCredential. For example, 


set ?FFCredential -SysCredential 


?FFDialogText The text of the Firefox authentication dialog box. 
?FFDomain The domain that is prompting for authentication. 
?FFMustSaveCredential The variable that controls whether SecureLogin requires users saving 


credentials for a specific realm or domain. 


?FFRealm The realm that is prompting for authentication. 


4.3 Application Definition Best Practices 


The following are some of the best practice rules to follow when creating an application definition. 
These rules make reading the application definition easier and also help if you need to make 
modifications in the future. 
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4.3.1 Symbols Used 


Table 4-1 Description of Symbols 


Symbol Description 


< > Angle brackets represent an item. 
For example, text, variable, or value. 
[ ] Square brackets represent an optional item. 
If an item is not marked with square brackets, it is a compulsory item. 


[ Indicates a line break 


4.3.2 Blank Line Between Sections 


NOTE: Always place the title after all other commands in the dialog block. 


Leave a blank line between sections, for example, between the dialog block and the rest of the 
application definition. 


Instead of Use 

# Logon Dialog Box # Logon Dialog Box 
Dialog Dialog 

Class #32770 Class #32770 
Title "Log on" Title "Log on" 
EndDialog EndDialog 


Type $Username #1001 
Type $Password #1002 Click #1 Type $Username #1001 
Type $Password #1002 


Click #1 
4.3.3 Capitalization 
Use capitalization where applicable. 
Table 4-2 Capitalization 
Instead of... Use... 
messagebox "some text" -yesno ?result MessageBox "Some text" -YesNo ?Result. 


4.3.4 Comments 


Use comments throughout to explain what each section does and how it does it. 
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Instead of... Use... 


Dialog # Written by B. Smith 2004, modified C. Silvagni 
Class #32770 2006 
Title # Logon Dialog Box 

"Log on" EndDialog Dialog 


Class #32770 
Title "Log on" 
EndDialog 


4.3.5 Indent Section 


Indent sections between pairs of commands, for example Dialog, Repeat, and If. Use an indent of 
three spaces. 


Instead of... Use... 

If -Text "Some text" If -Text "Some text" 
#Do thisElse #Do thisElse 

#Do This #Do this 

Endif EndIf 


4.3.6 Password Policy Names 


Password policy names must represent the program they are used for. Do not use numerical names. 


Instead of... Use... 


PasswordPolicy3 GroupwisePasswordPolicy 


4.3.7 Quotation Marks 


Always use quotation marks around segments of text in commands. 


Instead of... Use... 


Type TextOrlf -Text Login Type "Text"Orlf -Text "Log on" 


4.3.8 Regular Expressions 


Regular expressions are text patterns normally used for string matching. Regular expressions might 
contain a mix of plain text and special characters to indicate the kind of matching to be done. 


For example, if you are searching for any numeric character, then the regular expression that you use 
for the search is, “[0-9]”. 


The square [ ] brackets indicate that the character that is compared must match any one of the 
characters enclosed with in the brackets. The dash ( - ( between the zero (0) and nine (9) indicates that 
the range is between the number zero and nine. 
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If you need search for a special character, then you must use the backslash (\) before the special 
character. 


If your regular expression does not match any controls on a particular application screen, Novell 
SecureLogin will prompt you to check your regular expression and ensure the correct control is 
selected. Special characters in your regular expression might need to be escaped. 


The following table briefly describes the characters that can be used in regular expressions within 
Novell SecureLogin application definitions, in particular the RegSplit command detailed in 
Section 5.2.62, “RegSplit,” on page 133. 


Character Description 


\ (Backslash) The Vis an escape character indicating that the next character must be 
used as a regular search character and not as a special character. 


For example, the regular expression "\" matches a single asterisk and the 
expression “\\” matches a single backslash. 


A (Caret) The ^ is an anchor. If you use the ^ preceding any character, it searches 
the beginning character of any string. 


For example, the expression “A”” matches an “A” only at the beginning of 


the string. 
[^ (Square bracket and The ^ immediately following [, is used to exclude the characters within the 
Caret) square brackets from matching the target string. 


For example, the expression “[^0-9]” specifies that the target character 
must not be a numeral. 


$ (Dollar sign) The $ is an anchor. The $ matches the end of the string. 


For example, the expression “abc$” matches the substring “abc” only if it is 
at the end of the string. 


| (Vertical bar or pipe) The | allows the character on either side of the vertical bar (or pipe) to 
match the target string. 


For example, the expression “alb” matches a as well as b. 
. (Period or full stop) The . matches any character. 


* (Asterisk) The * indicates that the character to the left of the asterisk in the 
expression must match at least zero or more times. 


+ (Plus sign) The + indicates that the character to the left of the plus symbol in the 
expression must match at least once. 


? (Question mark) The ? indicates that the character to the left of the question mark must 
match at least zero or more than once. 


() (Parentheses) The ( ) enclosing a set of characters affects the order of pattern evaluation 
and also serves as a tagged expression that can be used when replacing 
the matched substring with another expression. 


[ ] (Square brackets) The [ ] enclosing a set of characters indicates that any of the enclosed 
characters might match the target character. 
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4.3.9 


4.3.10 


4.3.11 


Capture Groups 


If you are using the regular expressions to extract information rather than just match the text, use 
capture groups. You can use a captur egroup when using regular expressions to select credentials to 
be used based on a particular option from a comman dialog box. For example, the name or IP address 
of a particular server to which you want to connect. In such a scenario, Novell SecureLogin uses the 
capture group to make a unique name for a credential set and allows useres to have different 
credentials for different servers. 


For example, if a message indicating welcome Kerry to the Corporate server is displayed, then 
Kerry is the name of the user and Corporate is the name of the server. If you want to match just the 
text, Welcome .+ to the .+ server. If you want to use the server name as the name of the credential set, so 
that you can create other credential sets for other servers, add a capture group to the same regular 
expression and get Welcome .+ to the (.+) server. 


For more general information on regular expressions and usage refer the Boost Web site. (http:// 
www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html) 


Novell uses the Boost regular expression library (in Perl) when developing Novell SecureLogin. 
While other reference sites provide detailed and comprehensive information on regular expressions, 
only the expressions listed in the tables are supported by Novell. 


Switches 
Switches are placed directly after the command, for example, Type -Raw, If -Text. 


Table 4-3 Switches 


Instead of... Use... 
Type $Username -Raw Type -Raw $Username 
Variables 


All variable names start with a capital letter. 
Table 4-4 Variables 


Instead of... Use... 


Type $username Type $Username 


Writing Subroutine Sections 


Write subroutine sections at the bottom of the application definition and not partway through. 


The name of the subroutine should describe its function. Do not use a numeric name. The name 
should follow the capitalization rule. 


Wherever possible, use the Include command to create generic application definitions for 
frequently used elements, for example password change procedures. For common processes within 
the same application definition, use subroutines. 
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5.1 


5.1.1 


Command Reference 


This section contains the following information: 


¢ Section 5.1, “Command Reference Conventions,” on page 53 


+ Section 5.2, “Commands,” on page 56 


Command Reference Conventions 


This section consists of descriptions and examples of the commands that make up Novell 
SecureLogin application definitions. 


An index and summary is also included as Chapter 2, “Command Quick Reference,” on page 13. 


Command Information 


The information for each of the commands includes: 


+ “Use With values” on page 53 


+ “Type Values” on page 54 


Use With values 


Command 


Java 
Startup 
Terminal Launcher 


Advanced Web 


Web Wizard 


Windows 


Description 

Use as part of a Java* application definition. 

Use as part of a startup. 

Use as part of a terminal launcher application definition. 


Use as part of a manually created Web site or Internet application 
definition. Not compatible with the Web Wizard application definition 
language. 


NOTE: A predefined Web application and an Advanced Web application 
definition are the same. 


Use as part of application definitions created automatically by the Web 
Wizard. Web Wizard application definitions can be kept in their original 
XML format or converted to an ASCII script for advanced editing. 


Use as part of a Windows application definition. 
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5.1.2 


Type Values 


Command Description 

Action Performs an action, for example, the Type command types information 
into a field. 

Dialog specifiers Defines dialog boxes, for example, the Parent and Class commands. 

Flow control commands Directs Novell SecureLogin to a specific location in the application 


definition, for example, Repeat and EndScript commands. 


Variable manipulators Modifies variables, such as the Add and Subtract commands. 


Web Wizard Application Definition Conventions 


The SecureLogin advanced Web Wizard makes it easier for users to enable single sign-on Web sites 
and capture a user’s Web-based login details. When the user accesses a Web page from the browser, 
SecureLogin automatically launches the Web Wizard. 


ie 


SecureLogin 
© SecureLogin has detected a password field on this screen 


Window Title: Adobe - Sign In Show me 


Application URL 


O Do you want to single sign enable the screen? 
> I want to single sign using the default selections done by the wizard. 
> I want to single sign enable the screen using the wizard. (Recommended) 


> I do not want to single sign this screen at this time. 


> Never prompt me to single sign this screen. 


The Web Wizard captures the user's login details and adds them to the user's Web application 
definitions. 


When managing user's Web log in credentials, the Definition tab of the Advanced Setting page allows 
administrators to customize site and user credential details. Also available under the Definitions tab is 
an Advanced function that provides more functionality with their associated values and the option to 
convert the user’s login credentials to an application definition. 
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Applications - Application - “nytimes.com” 


+ 
₪ Java 
= ב"‎ Terminal Emulator Detak: Defintion | Settings | 
3 — a Select Site: [1 - The New ‘York Times > Login =] Delete 
E mac.com 
E hve.com 
= 168.33.19 Credentials o 
apele.com 
E hertz.com 8 1 
©) qartas.co הסוסה‎ The New York Tenes > Login 
(5) webex.com Submit None 
E nytimes.com Type bgn 
E mariott.com URL 
E dtvforum,info Doman Aak cOn 
O actewag).net.cu Retenes 
E) login, passport, nat Tae 
2 surreainetworks.com Bifocal . 
- 
‘ ar R Y << Standard | Convert To Application Definition 


For more details on how to manage application definitions, see Chapter 3, “Managing Application 
Definitions,” on page 25. 


Site Matching 


In SecureLogin version 6.0 and later, Web commands are added to allow much finer control of site 
matching. Detailed information of the loaded Web site can be matched and used to execute blocks of 
scripting commands. 


The technique used to specify constraints upon a site match are similar to those constraints used in 
windows scripting. 


Instead of Dialog/EndDialog commands, equivalent Site/EndSite commands have been created 
and can now be used. 


Within these Site blocks, Match commands can be used to filter a given site. If one of the specified 
match commands fails to match, then the site block will fail to match as a whole. For details of the 
Site/EndSite block command, see Section 5.2.80, “Site/Endsite,” on page 153. 


Form/Field/Option matching 


When matching a specific form, field or other match option it is often the case that multiple items will 
match the selection criteria. In these cases, the first item on the Web site which matches is considered 
to be the match. 


To access the other fields which also need to be matched, subsequent match commands may be 
added with the same selection criteria. 


NOTE: Matched items may only be matched once, and 


Each ID must be unique and cannot have been used previously. 


For example: 


MatchField #1:1 -type "password" 
MatchField #1:2 -type "password" 
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will match a site with two password fields. The first is given the ID '#1:1' the second is given the ID 
'#1:2' 


Form/Field/Option ID’s 


When matching a site, match methods are used to give specific fields, forms and options their own 
unique ID. 


Once the site has been successfully matched, the given ID is used in input commands to specify 
particular items. 


The actual ID's are denoted with a # followed by 1, 2 or 3 numbers, each separated by a colon - for 
instance, "#1:3:2". 


5.1.3 Auditing 


For auditing, use either the AuditEvent command built into Novell SecureLogin or the LogEvent 
command from the Windows Resource Kit. Refer the Novell SecureLogin 7.0 Administration Guide. 


For details, see Section 5.2.4, “AuditEvent,” on page 65 


5.1.4 One-Time Passwords 


The use of multiple passwords places a high maintenance overhead on large enterprises. Users are 
routinely required to use and manage multiple passwords, which can result in a significant cost, 
particularly with regard to calls to the help desk to reset forgotten passwords, or to ensure that all 
passwords are provisioned when a new user starts or are deleted when an existing user leaves the 
organization. 


One of the main benefits of implementing one-time password systems is that it is impossible for a 
password to be captured on the wire and replayed to the server. This is particularly important if a 
system does not encrypt the password went it is sent to the server, as is the case with many legacy 
mainframe systems. 


One-time passwords also offer advantages in terms of disaster recovery because the encryption key is 
used to generate the one-time password rarely changes. System restoration, which might be to a 
system version that is hours or many months old, can be achieved without consideration of restoring 
users’ passwords or notifying staff of new passwords. 


Novell SecureLogin provides a secure, robust and scalable infrastructure by integrating ActivCard* 
one-time password authentication functionality. 


For details of the GenerateOTP command, see Section 5.2.26, “GenerateOTP,” on page 87 


5.2 Commands 


* Section 5.2.1, “AAVerify,” on page 59 

+ Section 5.2.2, “Add,” on page 62 

+ Section 5.2.3, “Attribute,” on page 64 

+ Section 5.2.4, “AuditEvent,” on page 65 

+ Section 5.2.5, “BeginSplashScreen/EndSplashScreen,” on page 66 
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Section 5.2.6, “BooleanInput,” on page 66 
Section 5.2.7, “Break,” on page 67 

Section 5.2.8, “Call,” on page 68 

Section 5.2.9, “ChangePassword,” on page 69 
Section 5.2.10, “Class,” on page 70 

Section 5.2.11, “ClearPlat,” on page 71 

Section 5.2.12, “ClearSite,” on page 73 

Section 5.2.13, “Click,” on page 74 

Section 5.2.14, “ConvertTime,” on page 77 
Section 5.2.15, “Ctrl,” on page 78 

Section 5.2.16, “DebugPrint,” on page 78 
Section 5.2.17, “Decrement,” on page 79 
Section 5.2.18, “Delay,” on page 80 

Section 5.2.19, “Dialog/EndDialog,” on page 81 
Section 5.2.20, “Display Variables,” on page 82 
Section 5.2.21, “Divide,” on page 84 

Section 5.2.22, “DumpPage,” on page 85 
Section 5.2.23, “EndScript,” on page 85 

Section 5.2.24, “Event/Event Specifiers,” on page 86 
Section 5.2.25, “FocusInput,” on page 86 
Section 5.2.26, “GenerateOTP,” on page 87 
Section 5.2.27, “GetCheckBoxState,” on page 91 
Section 5.2.28, “GetCommandLine,” on page 91 
Section 5.2.29, “GetEnv,” on page 92 

Section 5.2.30, “GetHandle,” on page 92 
Section 5.2.31, “GetIni,” on page 93 

Section 5.2.32, “GetMD5,” on page 93 

Section 5.2.33, “GetReg,” on page 95 

Section 5.2.34, “GetDirectoryStatus,” on page 96 
Section 5.2.35, “GetSessionName,” on page 96 
Section 5.2.36, “GetText,” on page 97 

Section 5.2.37, “GetURL,” on page 98 

Section 5.2.38, “GoToURL,” on page 98 

Section 5.2.39, “Highlight,” on page 99 

Section 5.2.40, “If/Else/EndIf,” on page 99 
Section 5.2.41, “Include,” on page 104 

Section 5.2.42, “Increment,” on page 104 
Section 5.2.43, “KillApp,” on page 105 

Section 5.2.44, “Local,” on page 107 
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* Section 5.2.45, “MatchDomain,” on page 107 
+ Section 5.2.46, “MatchField,” on page 108 

+ Section 5.2.47, “MatchForm,” on page 110 

+ Section 5.2.48, “MatchOption,” on page 111 
+ Section 5.2.49, “MatchReferer,” on page 112 
+ Section 5.2.50, “MatchRegex,” on page 113 

+ Section 5.2.51, “MatchTitle,” on page 114 

¢ Section 5.2.52, “MatchURL,” on page 115 

¢ Section 5.2.53, “MessageBox,” on page 116 


+ Section 5.2.54, “Multiply,” on page 118 

+ Section 5.2.55, “OnException/ClearException,” on page 119 
+ Section 5.2.56, “Parent/EndParent,” on page 125 

+ Section 5.2.57, “PickListAdd,” on page 126 

+ Section 5.2.58, “PickListDisplay,” on page 128 

è Section 5.2.59, “PositionCharacter,” on page 129 

¢ Section 5.2.60, “PressInput,” on page 130 

+ Section 5.2.61, “ReadText,” on page 130 

Section 5.2.62, “RegSplit,” on page 133 

+ Section 5.2.63, “ReLoadPlat,” on page 134 


4 


4 


Section 5.2.64, “Repeat/EndRepeat,” on page 136 


4 


Section 5.2.65, “RestrictVariable,” on page 138 


4 


Section 5.2.66, “Run,” on page 140 
Section 5.2.67, “RunEX,” on page 140 
Section 5.2.68, “Select,” on page 141 


4 


+ 


4 


Section 5.2.69, “SelectListBoxItem,” on page 142 


4 


Section 5.2.70, “SelectOption,” on page 143 


4 


Section 5.2.71, “SendEvent,” on page 143 
Section 5.2.72, “SendKey,” on page 144 
Section 5.2.73, “Set,” on page 145 

Section 5.2.74, “SetCheckBox,” on page 146 
Section 5.2.75, “SetCursor,” on page 147 


4 


4 


4 


4 


4 


Section 5.2.76, “SetFocus,” on page 148 
Section 5.2.77, “SetPlat,” on page 149 


4 


4 


Section 5.2.78, “SetPrompt,” on page 151 


4 


Section 5.2.79, “-SiteDeparted,” on page 153 
Section 5.2.80, “Site/Endsite,” on page 153 
Section 5.2.81, “StrCat,” on page 155 
Section 5.2.82, “StrLength,” on page 156 


4 


4 


4 


4 


Section 5.2.83, “StrLower,” on page 156 


58 Novell SecureLogin Application Definition Guide 


5.2.1 


+ Section 5.2.84, “StrUpper,” on page 157 
+ Section 5.2.85, “Sub/EndSub,” on page 158 
+ Section 5.2.86, “Submit,” on page 159 


+ Section 5.2.87, “Substr,” on page 161 


+ Section 5.2.88, “Subtract,” on page 161 
+ Section 5.2.89, “Tag/EndTag,” on page 163 


+ Section 5.2.90, “TextInput,” on page 163 
+ Section 5.2.91, “Title,” on page 164 


¢ Section 5.2.92, “Type,” on page 165 


¢ Section 5.2.93, “WaitForFocus,” on page 170 
¢ Section 5.2.94, “WaitForText,” on page 171 


AAVerify 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Arguments 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later (arguments added in version 3.0) 


Action 


AAVerify [-Method <Defined method to use>] [-User <Username>] [-Tree <Tree 
name>] [?Result] 


Method 


The name of the advanced authentication method you wish to use. If not specified, 
AAVerify uses the method that was chosen during initial authentication to the 
directory. 


NOTE: You can specify multiple methods. 
User 


The name of the user you wish to use for the AAVerify command. If not specified, 
AAVerify reauthenticates the currently logged on user. 


Tree 
The name of the tree the user is in. You must use this with the User argument. 
[?Result] 


A variable name (preferably a temporary variable) that receives the result of the 
AAVerify. Set this variable to true for success or false for failure. 


?AAVerifyReturnCode 


A variable that will get set with the error code that is generated from the AAVerify re- 
authentication process (if any). 
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Description 


Syntax examples 


Use AAVerify with Novell SecureLogin re-authentication, Novell Modular 
Authentication Service (NMAS), or Novell Lightweight Directory Access Protocol 
(LDAP) to verify the user. It is typically used before the application user name and 
password are retrieved and entered into the login box. 


This provides application re-authentication using a strong login method. For 
example, a user might be forced to enter their smart card and PIN before the 
application will log on using single sign-on, even though the application natively 
knows nothing about smartcards and PINs. If the verification succeeds, the 
[?Result] is set to true, otherwise it is set to false. These additions are for Novell 
SecureLogin and NMAS. 


Novell SecureLogin re-authentication may use one of the following methods: 


* Password - your directory password. 
+ Smart card - if the smart card option has been selected during installation. 


* Logon method — Novell SecureLogin prompts for the same credentials as 
were used to log on for the current session. 


You can specify more than one method argument. In this case the user is allowed to 
re-authenticate with any of the specified methods. For example, you could use the 
command to request authentication using a fingerprint reader or smart card. 


NMAS or Novell LDAP-specific 


The method should be the name of the sequence as defined in the Novell 
environment. 


If AAVerify is called with no arguments, then the currently logged on user is 
re-authenticated using the login method that they used for their current session. 


NOTE: When the AAVerify command is added to an application definition, it only 
increases the security of the target application if it is not possible to alter the 
application definition. If the application definition could be modified or overridden, 
then the AAVerify command could be removed and there would be no additional 
security. For this reason it is imperative that application definition access be 
restricted through directory access controls and SecureLogin’s preferences, so that 
only a small, trusted group of administrators can modify, add and override 
application definitions. 


AAVerify 
AAVerify -Method "Enhanced Password" ?Result 


AAVerify -Method "Enhanced Password"-User "BSmith" - Tree "Production" ?Result 
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Example 1 


Example 2 


Windows application definition 


This example detects the login dialog box, but before Novell SecureLogin enters 
the user's credentials, it prompts the user to provide their re-authentication 
credentials. The credentials are not submited until the re-authentication has 
succeeded. 


# Logon Dialog Box 
Dialog 
Title "Log on" 
EndDialog 
AAVerify -Method "Enhanced Password" ?Result 
If ?Result Eq "True" 
Type $Username #1001 
Click #1 
Else 
Click #2 
MessageBox "Authentication failed. Please verify your 
smart card is inserted and your PIN is correct." 
EndIf 


Windows application definition 


The following example shows the use of exception handling with the 
OnExceptions command. 


Refer to Section 5.2.55, “OnException/ClearException,” on page 119 for further 
details and examples of OnException usage. 


Dialog 
Title "Log on" 
EndDialog 


OnException AAVerifyCancelled Call 
CancelSimpleLoginDialogCancelled 
OnException AAVerifyFailed Call CancelSimpleLoginDialogFailed 


AAVerify -method "smartcard" 
Type $Username #1001 
Click #1 


Sub CancelSimpleLoginDialogCancelled 
Click #2 
EndScript 

EndSub 


Sub CancelSimpleLoginDialogFailed 

Click #2 

MessageBox "Your re-authentication failed. Log on 
cancelled" 

EndScript 
EndSub 
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5.2.2 


Example 3 


Add 


Used with 


Novell SecureLogin 
version 


Type 


Usage 


Windows application definition 


The following example shows how to re-authenticate against the user's login 
method. 


Dialog 
Title "Log on" 
EndDialog 


OnException AAVerifyFailed Call AAVerifyFailed 
OnException AAVerifyCancelled Call AAVerifyCancelled 


If ?isPin Eq “true” 

AAVerify -method "smartcard" ?result 
Else 

AAVerify -method "password" ?result 
EndIf 


ClearException AAVerifyFailed 
ClearException AAVerifyCancelled 


Type $username 
Type \n 
Type $password 
Type \n 


Sub AAVerifyFailed 
Click #2 
MessageBox "Re-authentication failed." 
EndScript 

EndSub 


Sub AAVerifyCancelled 
Click #2 


EndScript 
EndSub 


Startup, Terminal Launcher, Web, or Windows 


3.0 or later 


Variable manipulator 


Add <Variable1> <Variable2> [?Result] 
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Arguments 


Description 


Syntax examples 


Example 


<Variable1> 


The first argument, the number to which the second argument will be added. This 
argument will also contain the result of the addition equation if the optional [?Result] 
argument is not passed in. If used without the [?Result] argument, <Variable1> 
must be a Novell SecureLogin variable. Otherwise, <Variable1> can be any 
numeric value. 


<Variable2> 


The second argument, the number added to the first argument in the equation. 
<Variable2> can be a Novell SecureLogin variable or numeric value. 


[?Result] 
Optional, the sum or result of the equation. 


Adds one number to another. The numbers can be written into the application 
definition or they can be variables. The result can be output to another variable or to 
one of the original numbers. 


Add 1 2 ?Result 

Add ?LoginAttempts ?LoginFailures 

Add ?LoginAttempts ?LoginFailures ?Result 
Add ?LoginAttempts 3 

Add ?LoginAttempts 3 ?Result 


Windows application definition 


This example reads the values of control IDs 103 and 104 into variables. From 
there they are added, and the result is typed into control ID 1 


ReadText #103 ?Number1 
ReadText #104 ?Number2 

Add ?Number1 ?Number2 ?Result 
Type ?Result #1 
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64 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


Advanced Web application definition 


3.5 or later 


Specifier 

Attribute <Attribute Name> <Attribute Name> 

< Attribute Name> 

Name of the HTML attribute to discover. 

< Attribute Value> 

The value the above HTML attribute must contain for the condition to be true. 


Use the Attribute specifier in conjunction with the Tag/EndTag command to specify 
which HTML attributes and attribute values must exist for that particular HTML tag. 


For more information, see Section 5.2.89, “Tag/EndTag,” on page 163. 
This example finds the form that has an attribute of Name with a value of Logon. 
Tag "Form" 


Attribute "Name" "Logon" 
EndTag 
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AuditEvent 


Use with 


Novell SecureLogin 
version 

Type 

Usage 


Arguments 


Description 


Example 


Startup, Terminal Launcher, Java, Web, or Windows application definitions to send 
an audit event to the Windows Event Log. 


6.0 or later 


Specifier 

AuditEvent [<message>] 

<message> 

The variable or text string passed to the Windows Event Log. 


NOTE: The functionality to send the contents of $variable or ?variable to the 
Windows Event Log is only supported in Novell SecureLogin 6.1SP1 or later 


Use AuditEvent to log Novell SecureLogin events to the Windows Event Log. 


Ifthe ChangePassword command is used to generate a $password variable, 
then a log entry is sent to the Windows Event Log. 


If the Audit platform agent is not present on the workstation nothing will be logged. 


AuditEvent “message” 


The parameter “message” is passed to the Windows Event Log. 


AuditEvent $message 


The parameter $message variable is passed to the Windows Event Log. 
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5.2.5 


BeginSplashScreen/EndSplashScreen 


Use with Terminal Launcher (Generic and Advanced Generic only) 

Novell 3.0.4 or later 

SecureLogin 

version 

Type Action 

Usage BeginSplashScreen 
EndSplashScreen 

Arguments None 

Description Use to display Novell splash screen across the whole Terminal Emulator window. 
This is used to mask any flickering caused by Novell SecureLogin scraping the 
screen for text. 
A Delay command at the start of the application definition ensures the emulator 
window is in place before the splash screen is displayed. 

Example Terminal Launcher application definition 
This example launches the emulator and the Novell SecureLogin waits 2 seconds for 
itto connect. The splash screen is displayed to cover the flickering, the login field is 
detected, the user name is entered, then the splash screen disappears. 
Delay 2000 
BeginSplashScreen 
WaitForText "Login:" 
Type $Username 
EndSplashScreen 
Type @E 

5.2.6 Booleaninput 
Use with Advanced application definitions created using the Web Wizard. 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


3.5.x or later 


Action 
BooleanInput #FormID:FieldID check "check" 
#FormID:FieldID 


The ID that was given to the matched field in the Site block using MatchField 
command. The FormID and FieldID must be unsigned integers. 


check "check" 
"check" is a Boolean value indicating a set or unset state for the specified field. 


Used inside a Site block to set the state of a Boolean field (either a check box or 
radio button). 


Novell SecureLogin Application Definition Guide 


5.2.7 


Example 


Break 


Use with 


Novell SecureLogin 
version 


Type 
Usage 
Arguments 
Description 


Example 1 


In this example the value of field #1:3 is being checked by the application definition. 


# === Logon Application Definition #2 == 
Google Initial Logon ==== 


Site Login -userid “Google Logon” -initial 
MatchDoimain “www.google.com” 

MatchField #1:1 -name “Email” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchField #1:3 -name “Cookie” -type “check” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 
FocusInput+1:2 -focus “true” 

BooleanInput +1:3 -check “false” 

PressInput 

Endscript 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Action 

Break 

None 

Use Break within the Repeat/EndRepeat commands to break out of a repeat loop. 
Windows application definition 


This example reads the screen and the content is searched for the words ‘log on’. If 
log on is found, the Repeat loop is broken and the application definition continues. If 
log on is not found, the application definition will check again. 


Dialog 
Class #32770 
Title "Log on" 
EndDialog 
Repeat 
ReadText #301 "?Text" 
If ?Text Eq "Log on" 
Break 
EndIf 
Delay 100 
EndRepeat 
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5.2.8 


Terminal application definition 


Example 2 


This example reads the terminal emulator screen and the content is searched for a 
successful log on (in this case the application main menu appears). Once the user 
has logged on, the Repeat loop is broken and the application definition continues. If 
the log on is not successful, the application definition will check again. Terminal 
emulators use repeat loops for error handling and to break out of the loop as 
appropriate. 


# Initial System Login 

WaitForText "ogin:" 

Type $Username 

Type @E 

WaitForText "assword: 

"Type $Password 

Type @E 

Delay 500 

# Repeat loop for error handling 

Repeat 

Check to see if password has expired 

If -Text "EMS: The password has expired." 
ChangePassword $Password 
Type $Password 


Type @E 
Type $Password 
Type @E 
EndIf 
#User has an invalid Username and / or Password stored. 
If -Text "Log on Failed" DisplayVariables "The 


username and / or password stored by SecureLogin is invalid. 
Please verify your credentials and try again. IT x453." 

Type $Username 

Type @E 

Delay 500 

WaitForText "assword:" 

Type $Password 

Type @E 

Delay 500 

Endif# 


Account is locked for some reason, possibly inactive. 

If -Text "Account Locked" MessageBox "Your account has been 
locked, possibly due to inactivity for 40 days. Please 
contact the administrator on x453." EndIf # Main Menu, user 
has logged on #successfully. If -Text "Application Selection" 
Break 

EndIf 

Delay100 


EndRepeat 


Call 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Flow control 


Call <SubRoutine> 
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Arguments <SubRoutine> 
The name of the subroutine called. This must be identical to the name given in the 
Sub command. 
Description Use the Call command to call and run a subroutine. When a subroutine is called, 
the application definition begins executing from the first line of the subroutine. 
When it is completed, the application definition resumes executing from the 
command immediately following the Call command. 
Subroutines are useful when you would otherwise have to repeat the same lines of 
application definition over again. 
Example Terminal application definition 
This example looks for the word Username, if it is found on the screen the 
subroutine Log on is launched. If Wrong Password is found, the subroutine 
WrongPassword is launched. 
Repeat 
If -Text "Username" 
Call "Login" 
EndIf 
If -Text "Wrong Password" 
Call "WrongPassword" 
EndIf 
EndRepeat 
#==Login Subroutine== 
Sub Login 
Type $Username 
Type QE 
Type $Password 
Type QE 
EndSub 
#==Wrong Password Subroutine== 
Sub WrongPassword 
DisplayVariables "The password entered is incorrect. 
Please check your password and click OK to try again. IT 
x4532." 
$Password 
Call Login 
EndSub 
ChangePassword 
Use with Startup, Terminal Launcher, Web, or Windows 


Novell SecureLogin 
version 


Type 


Usage 


3.5 or later 


Action 


ChangePassword <Variable> [<Text>] "Random" 
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Arguments <Variable> 
A normal or runtime variable in which the password is stored. 
[Text] 
The text you want displayed in the change password dialog box. 
[Random] 
Random will invoke the random password generator. 


Description Use ChangePassword to change a single variable in scenarios where password 
expiry is an issue. Set the <Variable> to the new password. 


The flag for this command is Random. 


If Random is: 


+ Set, the new password is generated automatically in compliance with the 
variable's password policy. 


+ Not set, a dialog box prompts the user to enter a new password. The new 
password is tried against any variable password policies that are in place. 
See also Section 5.2.65, “RestrictVariable,” on page 138. 


Syntax examples ChangePassword $NewPassword 
ChangePassword ?NewPassword "Please enter a new password" 
ChangePassword ?NewPassword Random 


Example Windows application definition 


This example detects the change password event. The application requires the 
current user name and password, and then a new password and confirmation of 
the new password. The application definition creates a backup of the old password 
in case the password change fails (which is detected by the message that is 
displayed), and then generates and enters a new password. 


# Change Password Dialog 

BoxDialog 

Class #32770 

Title "Change Password" 

EndDialog 

Set $PasswordBackup $Password 

Type $Password #1015 

ChangePassword $Password Random 

Type $Password #1005 

Type $Password #1006 

Click #1# 

Change Password Failed Dialog Box 

Dialog 

Class #32770 

Title "Change Password Failed" 

EndDialog 

# Set the password back as the password change failed 
$Password $PasswordBackup 

MessageBox "The change password process failed. Please retry 
the password change at your next log on. IT x453." 


5.2.10 Class 


Use with Startup, Windows 
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5.2.11 


Novell SecureLogin 3.5 or later 
version 


Type Dialog specifier 
Usage Class <Window-Class> 
Arguments <Window-Class> 
A string specifying the window class that this statement will match. 


Description When a window is created, it is based on a template known as a window class. The 
Class command checks to see if the class of the newly created window matches 
its <Window-Class> argument. 


If the window: 


+ Matches the <Window-Class> argument, the application definition continues 
to the next line. 


+ Does not match the <Window-Class> argument, execution continues at the 
next dialog statement. 


NOTE: Use the Novell Window Finder tool to determine the window class. 
Example Windows application definition 


This example checks the dialog box generated by the application to determine if the 
Window Class is #32770. If true and its title is log on, that section of the application 
definition will execute. If false, the application definition will check the next Dialog 
block. 


# Logon Dialog Box 
Dialog 

Class "#32770" 

Title "Log on" 
EndDialog 

Type $Username #1001 
Type $Password #1002 
Click #1 


ClearPlat 


For each dialog block in an application definition, the chosen user ID is reset and you must select it 
again. Select it again by using a SetPlat command or by having the user select again from a list. 


When an application first presents a login screen, Novell SecureLogin directs the user to select an 
appropriate user ID from a list. Novell SecureLogin enters the selected user ID's credentials into the 
application and submits them. 


Resolving issue of re-entering user ID details 


If the login fails due to incorrect credentials, Novell SecureLogin prompts the user to change the 
credentials. Novell SecureLogin does not retain user ID details and prompts the user to re-enter 
them. However, this could result in changing the wrong credentials if the user selects the incorrect 
user ID. 


To resolve this issue, use the SetPlat, ReLoadPlat and ClearPlat commands. ReloadPlat sets the 
current user ID to the one which was last chosen (for the given application) or leaves the user ID 
unset if a user ID has not been selected previously. ClearPlat resets the last chosen user ID. 
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See also Section 5.2.63, “ReLoadPlat,” on page 134 and Section 5.2.77, “SetPlat,” on page 149. 


Use with 


Startup, Terminal Launcher, Web, or Windows 


Novell SecureLogin 3.6.0 or later 


version 


Type 


Usage 


Arguments 


Description 


Example 


Action 


There are three main places where code needs to be added to use the ClearPlat 
command: 


Application startup When an application first starts up, use ClearPlat to clear the 
previously chosen platform. (Do this in a Windows application by adding an extra 
dialog statement for the main window.) 


Change Credentials Canceled Call ClearPlat if the user decides not to modify the 
chosen platform's credentials, thus giving them a chance to choose a different 
platform next time. 


Successful Logon Call ClearPlat to allow the user to log on again with a different 
platform at a later stage. 


None 


Use to reset the last chosen platform, causing subsequent calls to ReLoadPlat to 
do nothing. 


Windows application definition 


#== BeginSection: Application startup ==== 
Dialog 

Class "#32770" 

Title "Password Test Application" 
EndDialog 

ClearPlat 

# == EndSection: Application startup==== 
# ==== BeginSection: Log on ==== 
Dialog 

Class "#32770" 

Ctrl #1001 

Title "Log on" 

EndDialog 

ReLoadPlat 

SetPrompt "Username =====>" 

Type $Username #1001 

SetPrompt "Password =====>" 

Type $Password #1002 

SetPrompt "Domain =====> 

"Type $Domain #1003 

Click #1 

# ==== EndSection: Log on ==== 


## ====BeginSection: Log on successful ==== 
Dialog 

Class "#32770" 

Title "Log on successful" 

EndDialog 

ClearPlat 
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5.2.12 


Example 
(continued) 


ClearSite 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Click #2 
==== EndSection: Log on successful ==== 


==== BeginSection: Log on failure ==== 
Dialog 
Class "#32770" 
Title "Log on failure" 
EndDialog 
Click #2 
ReLoadPlat 
OnException ChangePasswordCancelled Call 
ChangeCancelled 
ChangePassword $password 
ClearException ChangePasswordCancelled 
Type -raw MA1t+F 
Type -raw L 
$ ==== EndSection: Log on Failure ==== 
# ==== BeginSection: Change Credentials Cancelled ==== 
Sub ChangeCancelled 
ClearPlat 
EndScript 
EndSub 
# ==== EndSection: Change Credentials 
Canceled === 


Web Wizard 


6.0 or later 


Action 
ClearSite "SiteName" 


"SiteName" 


The name of the site to clear, as specified in the matching Site/EndSite block that 


will be reset to initial. 


Used to clear the 'matched' status for a given site. This allows initial sites to match 


again and causes recent and subsequent sites to fail to match. 


The ClearSite command needs to have the complete URL specified in the line 


before the ClearSite command. 
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Examples In this example? the user is redirected to the Google home page and any previous 
user information is cleared. 


GotoURL “http://www. google.com” 


ClearSite Login 


In this example, the ClearSite command is used with as part of conditional 
statement and if a particular condition is true the user information is cleared. 


Site “Login” -subsequent 
MatchURL “here.now.com” 
endsite 
MessageBox "Would you like to login again?" -yesno ?Continue 
If ?Continue eq "Yes" 
Call LoginSub 
Else 
ClearSite Login 


EndIf 


5.2.13 Click 


Use with Java, Web, or Windows 


Novell SecureLogin 3.5 or later 
version 


Type Action 


Windows usage Usage One: Click <#Ctrl-ID> [-Raw] [-Right] Usage Two: Click <# Ctrl-ID > [-Raw [- 
x < X Co-ordinate > -y <Y Co-ordinate >]] Usage Three: Click [-order] <#Order- 
ID> 


Web usage Click <#Number> 
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Arguments 


<#Ctrl-ID> 
The ID number of the control to be pressed. 
[-order] 


If the control ID's are not constant, utilize the -order argument to instruct Novell 
SecureLogin to type into a control based on the creation order and not the tab 
order. For more information on the -order argument usage, see “Example 4” on 
page 168. 


<#Order-ID> 


For Windows application definitions, this parameter specifies which control based 
on the creation order in which to type the text. 


[-Raw] 

-Raw eliminates the mouse and sends a direct click. 

[-Right] 

-Right, used only with the -Raw flag, will send a right mouse click. 
<X Co-ordinate> 


X represents the horizontal co-ordinate relative to the client area of the application 
(not the screen). 


<Y Co-ordinate> 


Y represents the vertical coordinate relative to the client area of the application (not 
the screen). 


<#Number> 


The pound/hash symbol followed by the sequential number/control ID of the button 
to be pressed. 


Web specific 


The number of the button is determined by the Web page layout. See the 
Section 5.2.22, “DumpPage,” on page 85. 


Windows specific 
This is the control ID. Use the Windows Finder tool to discover the control ID. 
Java specific 


The index to use is put in an example application definition created by the Java 
wizard. 
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Description 


Syntax examples 


Example 1 


Example 2 


When used with Windows applications, the Click command sends a click 
instruction to the specified <#Ctrl-ID>. 


NOTE: If the button to be clicked does not have a control ID, the Type "\N" 
command will often click the default button in a Windows application. 


You can set the —Raw flag if the button or control does not respond to the Click 
command. The —Raw flag causes Novell SecureLogin to emulate the mouse and 
send a direct click message to the control. Using the -Right flag with the -Raw flag 
sends a right-click to the control. 


Setting the <#Ctrl-ID> to O (zero) sends the click instruction to the window on which 
the application definition is running. 


If -Raw is specified, then you can set the X coordinate and the Y coordinates. 
These coordinates are relative to the client area of the application, not the screen. 


NOTE: The borders of Windows Vista windows are substantially wider than those of 
Windows XP windows. Consequently, if your application definition will be used on 
both operating systems, you should use coordinates towards the top left of a Vista 
button or the bottom right of an XP button to ensure the same button is clicked in 
both operating systems. 


When used with Web application definitions, the Click command takes a single 
argument, which is the sequential number on the page of the button to be pressed. 
Click #3 will click the third button on the page. Keep in mind that, due to Web page 
layout and design, the sequential order of the buttons may not be obvious, and that 
you may have to use the DumpPage command to discover the field layout (see 
Section 5.2.22, “DumpPage,” on page 85). 


Click #1 

Click #1 -Raw -Right 
Click -X 12 -Y 24 
Click -order #1 


Windows application definition 


This example detects the login dialog box, the user name and password are 
entered, and button number 1 (in this case the logon button) is clicked. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title "Log on" 
EndDialog 

Type $Username #1001 
Type $Password #1002 
Click #1 


Web application definition 


This example enters the user name and password, and then the logon button is 
clicked. 


Type $Username 
Type $Password Password 
Click #1 
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5.2.14 


Example 3 


Example 4 


ConvertTime 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


Windows application definition 


This example uses the Java application, so there is no control ID. Instead, the 
Click command is told to click a particular place on the window. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title "Log on" 

End Dialog 

Type $Username 
Type $Password 
Click -X 12 -Y 24 


Windows application definition 


This example shows the use of the -order switch and demonstrates a possible 
‘order’ of the parameter. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title “Log on” 
EndDialog 

Type $Username #1001 
Type #Password #1002 
Click -order #1 


Startup, Terminal Launcher, Web, or Windows 


3.0.4 or later 


Variable manipulator 

ConvertTime <Time> <String Time> 
<String Time> 

The output variable. 


Use to convert a numeric time value, for example, ?CurrTime(system), into a 
legible format and store it in <String Time>. 


Windows application definition 


This example converts the time to a readable format and displays it in a dialog 
box. 


# Logon Dialog Box 

Dialog 

Class #32770 

Title "Log on" 

End Dialog 

ConvertTime ?CurrTime(system) ?Time 
MessageBox ?Time 
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5.2.15 


5.2.16 


Ctrl 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Syntax examples 


Example 


DebugPrint 


Use with 


Novell SecureLogin 


version 


Type 


Startup, Windows, Java 


3.5 or later 


Dialog specifier 

Ctrl <#Ctrl-ID> [<Regular Expression>] 
<#Ctrl-ID> 

The ID number of the control to check. 
[<RegEx>] 

The regular expression. 


Use the Ctr1 command to determine if a window or its children (any descendants) 
contains the control expressed in the <#Ctrl-ID> argument. The control ID number 
is a constant that is established at the time a program is compiled. 


Third party software control ID numbers may not be consistent from one version to 
the next. Use the Novell Window Finder tool to determine the control ID. 


Using the [<RegEx>] argument adds a further check that allows the application 
definition to skip to the next command. If the text on the specified <#Ctrl-ID> does 
not conform to the [<RegEx>], the application definition will skip to the next dialog 
statement as though the <#Ctrl-ID> did not exist. 


Ctrl #1 
Ctrl #1 "OK" 


Windows application definition 


This example tests the dialog box to see if it contains the correct control IDs with the 
correct values. If any of the control IDs are missing, or the text does not match, the 
application definition passes on to the next dialog block. 


# Logon Dialog Box 
Dialog 

Ctrl #1 "OK" 

Ctrl #2 "Cancel" 
Ctrl #3 "Help" 
Title "Log on" 
EndDialog 


Type $Username 


Type "\T" 
Click #1 


All 


6.0 or later 


Action 
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5.2.17 


Usage 


Arguments 


Description 


Syntax examples 


Example 


Decrement 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Syntax examples 


DebugPrint <Data> 

<Data> 

The text displayed to the user. 

Data can be several strings, variables, or a combination of both.. 


Use the DebugPrint command to display the text specified in the <Data> 
variable on a Debug console. The command can take any number of text 
arguments, including variables (for example, DebugPrint "The user " $Username " 
has just logged onto the system"). 


DebugPrint "Caught the login dialog” 
DebugPrint "Setting platform to " ?Platform 


Windows application definition 


This example displays the the text specified in the ?ServerName variable on the 
Debug console. 


# Logon Dialog 

Dialog 

Class "#32770" 

Title "Log on" 

EndDialog 

ReadText #1003 ?ServerText 

RegSplit "Server: (.*)" ?ServerText ?ServerName 
DebugPrint "Setting the platform to " ?ServerName 
SetPlat ?ServerName 

Type $Username #1001 

Type $Password #1002 

Click #1 


All 


3.5 or later 


Variable manipulator 

Decrement <Variable> 

<Variable> 

The name of the variable to decrease in value. 


Use the Decrement command to from a specified variable. For example, you can 
use decrement to count the number of passes a particular application definition has 
made. 


Once the number of instances is equal to the specified number, you can instruct the 
application definition to run another task or end the application definition. This is 
useful when configuring an application whose login panel is similar to other 
windows within the application, or to easily control the number of attempts a user 
can have to access an application. 


Also see Section 5.2.42, “Increment,” on page 104 


Decrement ?RunCount 
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Example Windows application definition 


Each time the application definition is run, a variable is incremented. This example 
counts the number of times the dialog box is dis-played. If the dialog box is 
displayed more than three times, the application is closed. If the login is successful, 
the count is reset. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title “Log on” 
EndDialog 


Decrement ?RunCount 

If ?RunCount Gt “3” 

MessageBox “Log on has been attempted too many times. The 
application will be closed.” 

KillApp “app.exe” 

Else 

Type $Username #1001 

Type $Password #1002 

Click #1 

EndIf 


# Logon Successful Message 
Dialog 

Ctrl #1 

Title “Logon Successful” 
EndDialog 


Set ?RunCount “0” 


5.2.18 Delay 
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Use with All 

Novell SecureLogin 3.5 or later 

version 

Type Action 

Usage Delay <Time Period> 

Arguments <Time Period> 
A period of time, expressed in milliseconds (1/1000 of a second), during which 
application definition execution is paused. 

Description Use the Delay command to delay the execution of the application definition for 


the time specified in the <Time Period> argument. 


The time specified in the <Time Period> argument is noted in milliseconds (for 
example, Delay 5000 creates a 5-second pause). You can use the Delay 
command to accommodate an introduction screen or another custom feature. 
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Example 


Windows application definition 


This example detects the login box, then the application definition waits half a 
second before acting upon it to make sure that the box is complete. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title "Log on" 
EndDialog 


Delay 500 
Type $Username #1001 
Type $Password #1002 
Click #1 


Dialog/EndDialog 


Use with 


Novell SecureLogin 
version 


Type 
Usage 
Arguments 


Description 


Java, Windows 


3.5 or later 


Dialog specifier 
Dialog/EndDialog 
None 


Use the Dialog/EndDialog command to identify the beginning and end of a dialog 
specification block respectively. You can use these commands to construct a dialog 
specification block, which consists of a series of dialog specification statements (for 
example Ctrl, Title, and so on). 


When a dialog block is executed, each of the dialog specification statements is 
executed in sequence. If any statement within the dialog block is not found, the 
entire dialog block is considered false, and the application definition execution 
proceeds to the next dialog block, if any. You need to specify as much information in 
the dialog block to make the dialog box (for example, Log on, Change Password, 
and so on) unique. 


The portion of the application definition that follows the EndDialog command is 
called the application definition body. Another dialog block, or the end of the 
application definition, terminates the application definition body. 
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Example Windows application definition 


This example tests the dialog box in order to determine its identity. If it is 
determined to be the login box, the application definition will parse the Type and 
Click commands to complete the login process. 


# Logon Dialog Box 
Dialog 

Ctrl #1 "OK" 

Title "Log on" 

Parent 

Title "Application 1" 
EndParent 

EndDialog 


Type $Username #1001 
Type $Password #1002 


Click #1 


5.2.20 DisplayVariables 


Use with All 

Novell SecureLogin 3.5 or later 

version 

Type Action 

Usage DisplayVariables [<User Prompt>] [<Variable> [<Variable>] ...] 
Arguments [<User Prompt>] 


Optional, customized text displayed in the Enter Novell SecureLogin Variables 
dialog box. This message can be defined in a runtime variable (see example 2). 


[<Variables>] 


The name of the variables for which you want the user prompted. If not specified, 
Novell SecureLogin will prompt for all variables that are used by the application 
definition. 
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Description 


Syntax examples 


Example 1 


Example 2 


Use the DisplayVariables command to display a dialog box that lists the 
user's stored variables (for example, $Username and $Password) for the current 
application. 


About editing variables The user can edit the variables from this dialog box. For 
example, if the login process is unsuccessful due to an incorrect user name or 
password, the DisplayVariables command prompts the user to edit the stored 
user name or password values. The login process proceeds as normal from that 
point. You can also specify a particular variable to display. 


If the <Variables> parameter is specified, DisplayVariables prompts only for the 
variables specified. Enter the replacement text in quotation marks after the 
DisplayVariables command. This replaces the default prompt text in the Enter 
Novell SecureLogin Variables dialog box. 


If there are no variables stored for the user, the first time Novell SecureLogin 
attempts to single sign-on to the application, the prompt will not be customized. 


Once there are variables stored for the user, the prompt will be customized when 
the application definition is run.The SetPrompt command can also be used to 
customize the prompt text in the dialog box. 


NOTE: You can use the OnException EnterVariablesCancelled command 
to prevent a user from canceling the DisplayVariables prompt. 


DisplayVariables 

DisplayVariables "Please enter your details" 
DisplayVariables "Please enter a new password" $Password 
DisplayVariables "Please enter your username and password" 
$Username $Password 

DisplayVariables "" $Username $Password 


Windows application definition 


This example detects the Wrong Password dialog box, and Novell SecureLogin 
prompts the user to enter a new user name and password. Once specified, Novell 
SecureLogin enters them into the dialog box, and the user clicks OK. 


# Wrong Password 

Dialog Box 

Dialog 

Class #32770 

Title "Wrong Password" 
EndDialog 

DisplayVariables "Enter a new username and 
password"?$Username $Password 
Type $Username #1001 

Type $Password #1002 

Click #1 


Windows application definition 
This examples passes the message in as a variable. 


Dialog 

Class "Notepad" 

Title "Untitled - Notepad" 

EndDialog 

Set ?Vars "\$Username" 

Set ?Msg "This is a DisplayVariables message" 
DisplayVariables ?Vars 

DisplayVariables ?Msg $Password 
DisplayVariables "testing" ?Vars 
DisplayVariables "testing" $Password $Username 
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5.2.21 Divide 


84 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Syntax examples 


Example 


Startup, Terminal Launcher, Web, or Windows 


3.0 or later 


Variable manipulator 
Divide <Variable1> <Variable2> [?Result] 
<Variable1> 


The dividend, the first argument, the number that is divided by the second 
argument. Also this argument contains the result ifthe optional [?Result] argument 
is not passed in. If used without the [?Result] argument, <Variable1> must be a 
Novell SecureLogin variable, either?Variable1 or $Variable1. Otherwise 
<Variable1> can be any numeric value. 


<Variable2> 


The divisor, the second argument, the number by which the first argument is 
divided. <Variable2> can be a Novell SecureLogin variable or a numeric value. 


[?Result]Optional, the quotient, the result of the equation. 


Use to divide one number by another. The numbers can be written into the 
application definition or they can be variables. The result can be output to another 
variable or to one of the original numbers. 


NOTE: This is an integer arithmetic that is 5/2, not 2.5. 


Divide "1" "2" ?Result 

Divide ?LoginAttempts ?LoginFailures 

Divide ?LoginAttempts ?LoginFailures ?Result 
Divide ?LoginAttempts "3" 

Divide ?LoginAttempts "3" ?Result 


Windows application definition 


This example read the values of control IDs 103 and 104 into variables. From 
there they are divided,and typed into control ID 1. 


ReadText #103 2Number1 

ReadText #104 ?Number2 

Divide ?Number1 ?Number2 ?Result 
Type ?Result +1 
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5.2.23 


DumpPage 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


EndScript 


Use with 


Novell SecureLogin 
version 


Type 
Usage 
Arguments 


Description 


Example 


Advanced Web application definition 


3.5 or later 


Action 

DumpPage <Variable> 

<Variable> 

The string variable to receive the page information. 


Use the DumpPage command to provide information about the current Web page. 
Use for debugging Web page application definitions. 


DumpPage ?dump 
MessageBox ?dump 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Action 
EndScript 
None 


Use the EndScript command to immediately terminate execution of the 
application definition. 


Windows application definition 


This example detects the login box, then Novell SecureLogin enters the user name 
and password, and the user clicks OK. If the Incorrect Password message is 
detected, Novell SecureLogin displays a message that the password was 
incorrect, and terminates the application definition. 


Dialog 

Title "Logon Failure" 
Ctrl #1 

EndDialog 


ReadText #65535 ?ErrorMsg 

If "Incorrect Password" -In ?ErrorMsg MessageBox "You have 
entered an incorrect password" 

EndScript 

EndIf 
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5.2.24 


5.2.25 


Event/Event Specifiers 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Syntax examples 


Focusinput 


Use with 
Novell SecureLogin 
version 


Type 


Usage 


Windows 


3.5 or later 


Dialog specifier 
Event <Event Specifier> 
<Event Specifier> 


The application event to monitor. This corresponds to a Windows event, which 
usually begins with WM_. 


For example, WM_COPYDATA, WM_GETOBJECT, WM_GETTEXT 


For detailed information on Windows events, see the Microsoft Developer network 
Web site. (http://msdn.microsoft.com). 


Microsoft's Spy++, or similar Windows message spy tools, are also useful for 
trapping event names in specific windows. Information on Spy ++ is also available 
on the MSDN Web site. 


Application definitions generally execute at the point when an application window 
is created. This corresponds to the WM_CREATE message that is received from 
an application window at start up. By adding the Event specifier to a dialog block, 
you can override this behavior, such that an application definition only executes 
when (and only when) the specified message is generated. If no Event specifier is 
given, it is equivalent to Event WM_CREATE. 


You can only apply the Event specifier within a Dialog and EndDialog statement 
block. Only one Event may be specified per Dialog block. If there is a requirement 
to monitor for multiple events, each must be specified within their own Dialog 
block. For more information, see MSDN or other documentation on the Win32 
messaging system. 

Dialog 

Class "someclass" 

Event WM_ACTIVATE 


EndDialog 
MessageBox "Caught the WM_ACTIVATE message" 


Startup, Terminal Launcher, Web or Windows and advanced application definitions 
created using the Web Wizard. 


3.5.x or later 


Action 


FocusInput #FormiID:FieldlD [-focus "focus"] 
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Arguments 


Description 


Example 


#FormID:FieldID 


The ID that was given to the matched field in the Site block using MatchField 
command. The FormID and FieldID must be unsigned integers. 


-focus "focus" 


Focuses the input field based upon the Boolean value of "focus". The Boolean 
value can be either "true" or "false. 


Used to focus on an input field based upon the Boolean value of "focus". 


In this example the value of field #1:2 is being checked by the application definition. 


# === Logon Application Definition #2 == 
# === Google Initial Logon ==== 
== == 2222 === e 222 oo 22 >= 


Site Login -userid “Google Logon” -initial 
MatchDoimain “www.google.com” 

MatchField +1:1 -name “Email” -type “text” 
MatchField +1:2 -name “Passwd” -type “password” 
MatchField #1:3 -name “Cookie” -type “check” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 

FocusInput +1:2 -focus “true” 

BooleanInput +1:3 -check “false” 

PressInput 

Endscript 


GenerateOTP 


GenerateOTP command supports two types of usage: 


+ “AISC Usage” on page 87 
+ “HOTP Usage” on page 89 


AISC Usage 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Startup, Terminal Launcher, Web, or Windows 


3.5.0 or later 


Action 


GenerateOTP -mode <string>-challenge <string> 
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Arguments 


Description 


<result> 


A variable that receives the value of the one-time password (OTP) that is 
generated. 


-mode 


Specifies the type of OTP that is dynamically generated. The default value for 
mode is set to AISC-SKI for smartcard OTP. Setting this to AISC-SKI makes 
SecureLogin use the Novell algorithm to generate an OTP based on the user’s 
smart card. This setting is deprecated and can be removed. 


-challenge 


When the OTP generated is based on a challenge/response or asynchronous 
mode, the challenge needs to be passed to the GenerateOTP command as an 
argument, normally by means of a script that reads the challenge from the screen. 


OTP is an authentication method specifically designed to avoid the security 
exposures inherit in traditional fixed and static passwords. 


OTPs rely upon a predefined relationship between the user and the authenticating 
server. The encryption key is shared between the user's token generator and the 
server, with each performing the pseudo-random code calculation at user logon. If 
the codes match, the user is authenticated. 


The GenerateOTP command incorporates OTP token generation functionality 
embedded in Novell’s smartcard technology. 


Novell’s soft tokens can be generated in synchronous and asynchronous modes 
which now allows soft tokens to be loaded onto mobile devices such as PDAs or 
be sent to cell phones as SMS text messages. 


Synchronous mode: Synchronous authentication of ’Novell’s timeplus-event 
authentication replaces static alphanumeric passwords with a pseudo-random 
code that is dynamically generated at configured time intervals, generally around 
once a minute. The pseudo-random code is based on a shared encryption key and 
the current time. 


Asynchronous mode: Asynchronous authentication or challenge response 
authorization replaces static alphanumeric passwords with a pseudo-random code 
that is dynamically generated based on a shared encryption key, the current time 
and a challenge/response combination. In Asynchronous mode the challenge 
must be passed to the GenerateOTP command as an argument. 


The application definition asynchronous example shows a typical command 
structure to enable OTP for use with Novell’s smart card technology. 


The application definition asynchronous example shows a typical command 
structure to enable OTP for use with Novell’s smart card technology. 
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Example 


HOTP Usage 


Use with 


Novell SecureLogin 


version 


In Novell SecureLogin version 6.0, the Generate0TP command was enhanced to 
integrate with smart cards. 


In Synchronous mode the GenerateOTP command requires the administrator to 
pass the -mode variable, AISC-SKI, to the command. 


In this instance AISC-SKI is the Novell smart card and SKI is the name of the 
applet used on the smart card. 


An example application definition enabling synchronous OTP encryption key 
distribution for use with smart cards is as follows: 


Dialog 

Title "Test App" 

EndDialog 

GenerateOTP -mode "AISC-SKI" ?0tpResult 
Type ?0tpResult #14 


In Asynchronous mode the challenge must be passed to the GenerateOTP 
command as an argument. This requires a script that reads the challenge variable 
from the screen. 


An example application definition enabling asynchronous OTP encryption key 
distribution for use with smartcards is as follows: 


Dialog 

Title "Test App" 

EndDialog 

ReadText #12 ?tmp 

GenerateOTP -mode "AISC-SKI" -challenge ?tmp ?0tp 
Type ?0tp #14 


It is assumed that a call without a challenge passed in is synchronous. The -mode 
parameter, instead of being passed in via the script, can also be created as a 
single sign-on variable in the script platform. 


If the -mode parameter is not passed in as a parameter to the GenerateOTP 
command, Novell SecureLogin will check for a variable named mode. Values 
passed into the command via the script will override values defined as variables. 
This is for future integration with Novell SecureLogin for Mobiles. 


NOTE: It is assumed that the acomx. 011 is present on the machine and in the 
path. If not, then additional code may be required to specify the location of this 
library file. 


The smartcard is assumed to be in the card reader at OTP generation time and a 
single card reader is also assumed. 


If the user's smart card has not been authenticated the user will be prompted to 
enter a PIN to unlock the card. This is required only once as the PIN is normally 
cached. 


Startup, Terminal Launcher, Web, or Windows 


7.0 SP2 or later 
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Type 
Usage 


Arguments 


Description 


Example 


Action 
GenerateOTP -METHOD=<XMethod> -MODE=<XMode> ?0TPResult 
-METHOD 


Defines the method or algorithm to generate the OTP. You can use the following 
value: 


+ OATH-HOTP 
-MODE 


Defines the mode of OTP generation and usage - software, hardware or smart 
token. You can use any one of the following values: 


+ SOFT 

+ HARD 

+ Al-SC(Smart Card) 
20OTPResult 


A variable that receives the value of the one-time password (OTP) that is 
generated. 


SecureLogin will enable using wizards to configure applications supporting OTP 
based authentication. Using wizards, users can configure OTP algorithm specific 
parameters with the options available to choose from using the wizard. 


# place your application definition here. 

Set ?0TPCredential "<NOTSET>" 

GenerateOTP -method "OATH_HOTP" -mode "SOFT" ?0TPCredential 
If ?0TPCredential Eq "<NOTSET>" 


DisplayVariables "Please specify all information." 
$0TPSecretKey $OTPCounter $OTPDigit 


GenerateOTP -method "OATH_HOTP" -mode "SOFT" ?0TPCredential 
EndIf 
MessageBox "OTP Generation Success" 


MessageBox ?0TPCredential 
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5.2.27 


5.2.28 


GetCheckBoxState 


Use with Advanced Web, Windows 
Novell SecureLogin 3.5 or later 
version 
Type Action 
Usage GetCheckBoxState <#ltem Number> <Variable> 
Arguments <Item Number> 
The ID of the check box. 
<Variable> 
The target variable for the status of the specified check box. Value returned is 
Checked or Unchecked. Partially selected tristate check boxes will be returned as 
Unchecked. The variable can be a question mark (?) or a dollar sign ($) variable. 
Description Use the GetCheckBoxState command to return the current state of the specified 
check boxes. 
Example GetCheckBoxState #25 ?statel 
GetCheckBoxState +26 ?state2 
MessageBox ?statel 
MessageBox ?state2 
GetCommandLine 
Use with Startup, Windows 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


3.0.4 or later 


Action 

GetCommandLine<Variable> 

<Variable> 

This variable defines where to store the captured command line. 


Use the GetCommandLine command to capture the full command line of the 
program that is loaded and save it to the specified variable. 


NOTE: You can use the GetCommandLine to detect and differentiate backend 
systems and databases for use with multiple logons in the SAP application. 


Windows application definition 


This example reads the command line of the application, and then tests the line to 
see if it is Notepad.exe. If it is, Notepad is closed. If it is not, the application 
definition ends. 


GetCommandLine ?Text 

If ?Text Eq "\"C:\Windows\System32\notepad.exe\"" 
KillApp Notepad.exe 

EndIf 
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5.2.29 GetEnv 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


5.2.30 GetHandle 


92 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 1 


All 


3.5 or later 


Action 

GetEnv <EnvVar> <Variable> 

<EnvVar> 

This is the environment variable name you wish to retrieve. 

<Variable> 

This variable defines where to store the retrieved environment variable data. 


Use the GetEnv command to read the value of an environment variable and 
saves it in the specified variable. 


Windows application definition 
GetEnv "SESSIONNAME" ?SessionName 
If ?SessionName eq "console" 


MessageBox "Running from Citrix Server Console" 
EndIf 


Windows 


6.1.0 or later 


Action 

GetHandle <Variable> 

<Variable> 

This variable defines where to store the captured handle. 


Use GetHandle to capture the unique handle of the window that the Windows 
application definition script is activated on. 


GetHandle is used to retrieve the handle so that the value is passed to 
TLaunch.exe to inform the terminal launcher what window to interact with, or to 
pass the value to any other application. 


Windows application definition 


GetHandle ?winHandle 
MessageBox ?winHandle 
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5.2.31 


5.2.32 


Example 2 


Getini 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


GetMD5 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Windows application definition 


GetReg "HKLM\Software\Microsoft\wWindows\CurrentVersion\App 


Paths\SLProto.exe\Path" ?SLLocation 
If ?SLLocation eq "<NOTSET>" 
EndScript 

EndIf 


GetHandle ?PuttyHWND 
Strcat ?TLaunch ?SLLocation "tlaunch.exe" 
Strcat ?TLaunchHWND "/hwnd" ?PuttyHWND 


Run ?TLaunch "/auto" "/ePutty" "/1" "/pPutty - Detection and 


Login" "/t" "/q" "/s" ?TLaunchHWND 


Windows, Web, Terminal, Java 


3.5 or later 


Action 
Getini <ini file> <section> <key> <variable> 


<Ini File> 


This is the file name from which you wish to read the section or key. 


<Section> 

Name of the section that contains the key name. 
<Key> 

Name of the key to read. 


<Variable> 


This variable defines where to store the retrieved environment variable data. 


Use the Get Ini command to read data from INI file. 


Windows application definition 


GetIni "C:\Program Files\Lotus\Notes\Notes.ini" "Notes" 


"KeyFileName" ?NotesDefaultIDFileSetPlat 


Windows 


6.0 or later 


Action 


GetMD5<Value> 


Command Reference 


93 


94 


Arguments 


Description 


Example 


<Value> 
Returns the MD5 hash value. 


Use the GetMD5 command to generate an MD5 hash value of the current process 
the script is running for. GetMD5 will only work with Win32 scripts. 


Message-Digest algorithm 5 (MD5) is employed in Novell SecureLogin and can be 
used to check the integrity of files against a known hash value. 


MD5 hash values are widely used in software to provide assurance that a 
particular file has not been altered. The administrator can compare a published 
MD5 sum with the checksum of another file to recognize corrupt or incomplete 
files, particularly for large executable files. 


In a Windows application definition the MD5 hash value is stored as a variable 
which is then passed in as the argument to the command, which could be a ?tmp 
or $hash_value type variable. 


GetMD5 ?tmp 


or 


GetMD5 $hash_value 


The MD5 hash value would normally be obtained with the Window Finder tool on a 
window from the application, and also the MD5 hash from Window Finder. This 
MD5 value would then be put in a script and the GetMD5 command would be used 
to compare the two MD5 hash values. If the MD5 hash values do not match, the 
executable file may have been altered. 
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5.2.33 


GetReg 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


All 


3.5 or later 


Action 

GetReg <RegEntry> <Variable> 

<RegEntry> 

This is the registry entry to read. 

<Variable> 

This variable defines where to store the retrieved environment variable data. 


Use the GetReg command to read data from the registry and save it in the 
specified variable. 


The following is format for the registry entry input: HIVE\KEY\Value 
ValueValid hives are: 


"HKCR "HKEY_CLASSES_ROOT "HKCC "HKEY_CURRENT_CONFIG "HKCU 
"HKEY_CURRENT_USER "HKLM "HKEY_LOCAL_MACHINE "HKU "HKEY_USERS 


Windows application definition 


GetReg "HKLM\Software\ABCCorp\ProductID"?ProductID 
If ?ProductID noteq "xxxxxxxxxx" 

#Not corporate desktop 

EndScript 

EndIf 
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5.2.34 GetDirectoryStatus 


Use with All 


Novell SecureLogin 7.0 or later 


version 
Type Variable manipulators 
Usage GetDirectoryStatus <?StatusVariable> 
Arguments <?StatusVariable> 
The target variable to which the value of the primary status is copied. 
The value returned is either online or offline. 
Description Use the GetDirectoryStatus command to find out whether Novell 
SecureLogin can connect to the directory or not. 
The status is online if the network is up, Novell SecureLogin connects to the 
directory, and the user is working in online mode. 
The status is online if either the network is down, the network is up but the 
directory is unavailable, or the user chooses to work offline mode. 
Example GetDirectoryStatus ?status 


If ?status eq “online” 
#online instructions 
Endif 

If ?status eq “offline” 
#offline instructions 
Endif 


5.2.35 GetSessionName 


Use with Terminal Emulator 


Novell SecureLogin 3.5 or later 


version 

Type Action 

Usage GetSessionName <?Variable> 

Arguments <Variable> 
The target variable that the session name is copied into. 

Description Use the GetSessionName command to find the current HLLAPI session name 
that is used to connect and returns it to the specified variable. 

Example Windows application definition 


GetSessionName ?Session_name 


96 Novell SecureLogin Application Definition Guide 


5.2.36 


GetText 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


Web, Terminal Launcher 


3.0 or later 


Action 

GetText <Variable> 

<Variable> 

This variable defines where to store the captured text. 


Use the Get Text command to get all of the text from the screen and save it to the 
specified variable. It is used in large Web application definitions that contain several 
If -Text statements. 


In Netscape, each If -Text statement screen scan to find the specified text caused 
the screen to flicker. However, using GetText (for example If ?Text -in 
?FromGetText), the application definition can contain multiple If -Text commands 
with only one scan of the screen. 


Web application definition 


This example copies the text content of the Web page to the ?Text variable. Novell 
SecureLogin tests for the presence of the word ‘Logon’. If Logon exists, Novell 
SecureLogin enters the credentials and submits them automatically. 


GetText ?Text 

If "Log on" -In ?Text 
Type $Username 

Type $Password Password 
EndIf 
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5.2.37 GetURL 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


5.2.38 GoTOURL 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Web 


3.0 or later 


Action 

GetURL <Variable> 

<Variable> 

This variable defines where to store the captured URL. 


Use the GetURL command to capture the URL of the site that is loaded and save it 
to the specified variable. 


Web application definition 


This example copies the URL of the Web site to the ?URL variable and tests the 
URL to see if it matches text being searched for. If it does, Novell SecureLogin 
pops up a message box and redirects the user to the intranet. 

GetURL ?URL 

If "Log off" -In ?URL 

MessageBox "You have chosen to log off the application. You 
will now be redirected to the intranet home page." 


GoTOURL "http://Intranet" 
EndIf 


Web 


3.5 or later 


Action 

GoToURL <URL> [<-frame>] 

<URL> 

The URL to which the browser will navigate. 

<-frame> 

Opens the URL in the frame which started the application definition. 


Use the GOTOURL command to make the browser navigate to the specified URL. By 
default the command opens the new Web page in the main window, rather than the 
frame that started the application definition. 


When using the -frame option on a framed Web page, the URL redirect occurs only 
in the current frame rather than the parent window. 


You must include http://. 
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5.2.39 


5.2.40 


Example 


Highlight 


Use with 


Novell SecureLogin 
version 


Type 


Description 


Example 


IffElse/Endlf 


Use with 


Novell SecureLogin 
version 


Type 
Usage 1 


Usage 2 


Web application definition 


This example detects an incorrect password message, displays a message box 
informing the user, and then browses the Novell Web site. 


If -Text "Incorrect Password" 

MessageBox "You have entered an incorrect password" 
GoTOURL "http://www.Novell.com" 

EndIf 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Action 
Use the Highlight command to set the focus of the Web page on a field. 


The command is useful for pages that do not have any control selected after 
loading or for any fields that change the behavior after gaining focus. 


It functions similar to the SetFocus command in Windows scripts. 
Web application definition 


If -Text "Logon" 
Highlight #1 

Type $Username #1 
Highlight #2 

Type $Password #2 
Type "\\" 

EndIf 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Flow control 


If <Value1> <Gt|Lt> <Value2> 
#Do This 

[Else] 

#Do This 

EndIf 


If <Value1> <Eq|NotEQ > <Value2> [-I|-S] 
#Do This 

[Else] 

#Do This 

EndIf 
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Usage 3 If <Value1> <-In|-NotIn> <Value2> [-1|-S] 
#Do This 
[Else] 
#Do This 
EndIf 


Usage 4 If -Text [-Frame] <Text> 
#Do This 
[Else] 
#Do This 
EndIf 
Usage 5 If -Exist|-NotExist <Variable> 
#Do This 
[Else] 
#Do This 
EndIf 
Arguments <Value1> 
The left side of the expression for evaluation. 
<Value2> 
The right side of the expression for evaluation. 
<Text> 


The text for which you are searching. 
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Description 


Syntax examples 


Use the If command to establish a block to execute if the expression supplied is 
true. The Else command works inside an If block. The Else command is 
executed if the operator in the If block is false. Use the EndIf command to 
terminate the If block. 


Text comparison operators supported The text comparison operators 
supported by the If command are: 


+ Eq: True if the left side is equal to the right side. 

+ NotEQ: True if the left side is not equal to the right side. 

+ -In: True if the left side is a substring of the right side. 

+  -Notin: True if the left side is not a substring of the right side. 


+ -SiteDeparted: Checks if the current document is still active or not. 


When using these text comparison operators, you may optionally specify whether 
the comparison is to take into account the case of the strings being compared. If -I 
is specified, the comparison is case insensitive. If -S is specified, then the 
comparison is case sensitive. By default the Eq and NotEQ operators are not case 
sensitive, while the -In and -Notin operators are case sensitive. 


An operator is also supplied to directly query the application for a particular string:- 
Text: Evaluates to true if the specified text is found in the application windows of 
the application. For Internet Explorer application definitions, you can supply an 
optional -Frame argument, which restricts the command to look for the specified 
text in the current frame. 


Numerical comparison operators supported Two numerical comparison 
operators are supported by the If command, Gt and Lt. The command evaluates 
to true if the left side is greater than or less than (respectively) the right side. This 
is a numerical comparison, so the left and right sides must be numbers. 


An operator is supplied to check for the existence of a stored variable: 


+ -Exists: True if the specified variable exists. 


+ -NotExist: True if the specified variable does not exist. 


If $Number NotEQ "1" 
MessageBox "NotEQ 1" 
Else 

MessageBox "Eq 1" 
EndScript 

EndIf 


If ?Value1 Gt ?Value2 
If -Text "Log on" 

If -Exists $RunBefore 
If "Log on" -In ?Text 
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Example 1 Web application definition 


This example tests for an incorrect password. If it is found, an incorrect password 
message box is displayed. If the error message is not found, Novell SecureLogin 
logs in as normal. 


If -Text "Incorrect Password" 

DisplayVariables "You have an incorrect password. Please 
verify it and retry log on." 

EndScript 

Else 

Type $Username 

Type $Password Password 

EndIf 


Example 2 Windows application definition 


Each time the application definition is run, a variable is incremented. This example 
counts the number of times the dialog box is displayed. If it is displayed more than 
three times, the application is closed. If the log on is successful, the count is reset. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title “Log on” 
EndDialog 


ReadText #1001 ?Username 


If -Exists $Username 
Else 
Set $Username ?Username 
EndIf 
Increment ?RunCount 
If ?RunCount Gt “3” 
MessageBox “Log on has been attempted too many times. The 
application will be closed.” 
KillApp “app.exe” 


Else 
Type $Username #1001 
Type $Password #1002 


Click #1 
EndIf 
# Logon Successful Dialog Box 
Dialog 

Ctrl #1 

Title “Log on successful” 
EndDialog 


Set ?RunCount “0” 
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Example 3 


Example 4 


Web application definition 


This example copies the text content of the Web page to ?WebText. The variable 
is then tested to see if ‘Log on’ is present. If it is, Novell SecureLogin performs the 
login process. If it is not present, the application definition is terminated. 


GetText ?wWebText 
If “Log on” -In ?WebText 
Type $Username 
Type $Password Password 
Else 
EndScript 
EndIf 


Startup 


This example tests, upon Novell SecureLogin loading, to see if Novell 
SecureLogin has been run by the user. If it has not, Novell SecureLogin sets the 
variable so that the message is only displayed once, and then displays a welcome 
message along with the option for further details on Novell SecureLogin. 


If -NotExist $LoadedBefore 
EndScript 
Else 
MessageBox -YesNo ?Result “Welcome to SecureLogin Single 
Sign-On, a new password management tool that will save you 
the hassle of remembering your passwords. Would you like more 
details on how to use SecureLogin and what it can do for 
ou?” 
Set $LoadedBefore “Yes” 
If ?Result Eq “Yes” 
GoTOURL “http://www.Novell.com/securelogin.htm” 
EndIf 
EndIf 
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5.2.41 Include 


Use with All 

Novell SecureLogin 3.0 or later 

version 

Type Flow control 

Usage Include <Platform-Name> 

Arguments <Platform-Name> 
The name of the application definition to include. 

Description Use the Include command to share commonly-used application definition 
commands by multiple applications. The application definition identified by 
<Platform-Name> is included at execution time into the calling application 
definition. The application definition included with the Include command must 
comprise commands supported by the calling application. 

Example Windows application definition 


This example detects the login dialog, the Notepad.exe application definition is 
executed, and then the user's credentials are entered. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title “Log on” 
EndDialog 


Include “Notepad.exe” 
Type $Username #1001 
Type $Password #1002 
Click #1 


5.2.42 Increment 


Use with All 

Novell SecureLogin 3.5 or later 

version 

Type Variable manipulator 
Usage Increment <Variable> 
Arguments <Variable> 


The name of the variable to increase in value. 
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5.2.43 


Description 


Syntax examples 


Example 


KillApp 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Use the Increment command to add to a specified variable. For example, you 
can use increment to count the number of passes a particular application definition 
has made. 


Once the number of instances is equal to the specified number, you can instruct 
the application definition to run another task or end the application definition. This 
is useful when configuring an application whose login panel is similar to other 
windows within the application, or to easily control the number of attempts a user 
can have to access an application. 


Also see Section 5.2.17, “Decrement,” on page 79 
Increment ?RunCount 
Windows application definition 


Each time the application definition is run, a variable is incremented. This example 
counts the number of times the dialog box is displayed. If the dialog box is 
displayed more than three times, the application is closed. If the log on is 
successful, the count is reset. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title “Log on” 
EndDialog 


Increment ?RunCount 
If ?RunCount Gt “3” 
MessageBox “Log on has been attempted too many times. The 
application will be closed.” 
KillApp “app.exe” 
Else 
Type $Username #1001 
Type $Password #1002 


Click #1 
EndIf 
# Logon Successful Message 
Dialog 

Ctrl #1 

Title “Log on successful” 
EndDialog 


Set ?RunCount “0” 


All 


3.5 or later 


Action 
KillApp <Process-Name> 


KillApp <-Title> 
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Arguments <Process-Name> 

The name of the process to terminate. 

-title “Application title” 

The title of the process to terminate. 
Description Use the Kil1App command to terminate an application. 
Example 1 Windows application definition 


Each time the application definition is run, a variable is incremented. This example 
counts the number of times the dialog box is displayed. If the dialog box is 
displayed more than three times, the application is closed. If the log on is 
successful, the count is reset. 


# Logon Dialog Box 
Dialog 
Title “Log on” 
Class #32770 
EndDialog 
Increment ?RunCount 
If ?RunCount Gt “3” 
MessageBox “Log on has been attempted too many times. The 
application will be closed.” 
KillApp “app.exe” 


Else 
Type $Username #1001 
Type $Password #1002 


Click #1 
EndIf 
# Logon Successful Message 
Dialog 
Title “Log on successful” 
Ctrl #1 
EndDialog 


Set ?RunCount “0” 
Example 2 Windows application definition 


Same application definition as used in Example 1, however, the KillApp process is 
specified by title. 


Dialog 
Title “Login Simple” 
Class #32770 
EndDialog 
Increment ?RunCount 


If ?RunCount Gt “3” 

MessageBox “Log on has been attempted too many times. The 
application will be closed.” 

KillApp -title “Login Simple” 
Else 

Type $Username #1001 

Type $Password #1002 


Click #1 

EndIf 

# Logon Successful Message 

Dialog 
Title “Login - Simple Successful” 
Ctrl #1 

EndDialog 


Set ?RunCount “0” 


106 Novell SecureLogin Application Definition Guide 


5.2.44 Local 


Use with All 

NovellSecureLogin 3.5 or later 

version 

Type Variable manipulator 

Usage Local <?Variable> 

Arguments <?Variable> 
The runtime variable to declare as local. 

Description Use the Local command to declare that a runtime variable will only exist for the 
lifetime of the application definition. Local runtime variables are used in the same 
way as normal runtime variables and are still written as ?Variable. 

Declare local runtime variables as local by using the Local command, followed by 
the variable name. When runtime variables are declared local, you cannot set them 
back again. You can declare a runtime variable local at any time in an application 
definition. 

Using local runtime variables increases the performance of Novell SecureLogin, 
although only slightly. Local runtime variables are used to run application definitions 
multiple times without storing the runtime variables between each run of the 
application definition. 

Local runtime variables are also used to prevent runtime variables from overwriting 
each other, which could happen if two instances of an application definition are 
running at the same time. For example, use the Local command if two instances 
of Terminal Launcher are running, each instance running the same application 
definition but attached to different emulator sessions. 

Example Windows application definition 


This example declares a variable as local, and then uses it to count the number of 
times a dialog box is displayed. If the dialog box is displayed too many times, Novell 
SecureLogin will alert the user, then close the application. 


# Invalid Logon Message 
Dialog 

Class #32770 

Title "Logon Failure" 
EndDialog 

Local ?RunCount 

Increment ?RunCount 

If ?RunCount Gt "5" 
MessageBox "Closing application" 
KillApp "PasswordText.exe" 
EndIf 

Type $Username 

Type $Password 


5.2.45 MatchDomain 


Use with Advanced application definitions created using the Web Wizard. 
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Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


5.2.46 MatchField 
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Use with 


Novell SecureLogin 
version 


Type 


Usage 


3.5.x or later 


Action 

MatchDomain "Domain" 

Domain 

The domain name or address to be matched. 


Use MatchDomain inside a Site block to filter a site based on its domain. If the 
domain doesn't match, the Site block fails to match. 


The domain matched is a normally a low level domain name such as 
www.yahoo.com and not www.yahoo.com/mymail/login 


In this example the site www.google.com is being matched by the application 
definition. 


# === Logon Application Definition #2 == 
# === Google Initial Logon ==== 
כככ-ככ-כם-2כככם-כככככככ-ככככככ-כככככשכ2-‎ 


Site Login -userid “Google Log On” -initial 
MatchDomain “www.google.com” 

MatchField #1:1 -name “Email” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchField #1:3 -name “Cookie” -type “check” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 
FocusInput#1:2 -focus “true” 

BooleanInput #1:3 -check “false” 

PressInput 

Endscript 


Advanced application definitions created using the Web Wizard. 


3.5.x or later 


Action 


MatchField #FormID:FieldID [-optional] [-name "name"] [-type "type" [-value 
"value" [-defaultValue "defaultValue" 
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Arguments #FormlID:FieldID 


The ID to be given to the matched option within the field, building from the #FormID 
of the associated form. The FormID and FieldID must be unsigned integers. The 
combined #FormID:FieldID must be unique within the site block. 


-optional 


Specifies that matching this field is not required to successfully match the parent 
form. 


-name "name" 
Match against the field name. 


-type "type" 
Match against the field type. Type can be one of the following: 
+ Button 
+ Checkbox 
+ File 
* Image 
+ Hidden 
* Password 
* Radio 
+ Reset 
+ Submit 
+ Text 
+ TextArea 
* Select-multiple 
+ Select-one 
-value "value" 
Match against the field value. 


-defaultValue "defaultValue" 


Match against the field’s default value. 


Description Use MatchField to filter a form based on the presence of a particular field. If the field 
fails to match and it is not specified as optional, then the parent form will fail to 
match. 
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Example This example would locate the Web page fields Email, Password and Cookie within 
the Web site www.google.com .com matched by the application definition. 


# === Logon Application Definition #2 == 
# === Google Initial Logon ==== 
Peas a SSS S SS SSS SSS SSS SSS SSS SSS SSS SSS SSS SS 


Site Login -userid “Google Log On” -initial 

MatchForm #1 -name “log on” 

MatchDomain “www.google.com” 

MatchField #1:1 -name “Email” -type “text” 

MatchField #1:2 -name “Passwd” -type “password” 

MatchField #1:3 -name “Cookie” -type “check” 

MatchField #1:4 -name “SAVEOPTION” -type “checkbox” -value 
“VES” 

MatchField #1:5 -name “Submit2” -type “submit” 


EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 
TextInput #1:2 -value “$Password” 
FocusInput+1:2 -focus “true” 
BooleanInput +1:3 -check “false” 
BooleanInput +1:4 -check “false” 


PressInput 
Endscript 
5.2.47 MatchForm 
Use with Advanced application definitions created using the Web Wizard. 


NovellSecureLogin 3.5.x or later 


version 
Type Action 
Usage MatchForm #FormID [-optional] [-name "name"'] [-action "action"] [-method 


"method" [-target "target"] 
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5.2.48 


Arguments 


Description 


Example 


MatchOption 


Use with 


#FormID 


The ID to be given to a matching form. The ID must be an unsigned integer prefixed 
with # and unique within the site block. 


-optional 
Specifies that matching this form is not required to successfully match site. 
-name "name" 


Specifies the form name to match against. The form name is an optional value 
given to a form by the creator of the Web site. 


-action "action" 


Specifies the form action to match against. The URL to which the form content is 
sent for processing. 


-method "method" 


Specifies the form method to match against. The method or how to send the form 
data to the server. 


-target "target" 


Specifies the form target to match against. The window or frame at which to the 
form targets its contents. 


Use MatchForm to filter a site based on the presence of a particular form. If the 
form fails to match and it is not specified as optional, then the site will fail to match. 


In this example the form named ‘log on’ within the Web site www.google.com .com 
is being matched by the application definition. 


# === Logon Application Definition #2 == 
# === Google Initial Logon ==== 
Poe=Sa= SS SSSSSSSS SS SS et 


Site Login -userid “Google Log On” -initial 
MatchForm #1 -name “log on” 

MatchDomain “www.google.com” 

MatchField #1:1 -name “Email” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchField #1:3 -name “Cookie” -type “check” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 
FocusInput+1:2 -focus “true” 

BooleanInput +1:3 -check “false” 

PressInput 

Endscript 


The form name may be a “null” 


an 


MatchForm #1 -name 


Advanced Web application definitions created using the Web Wizard. 


NovellSecureLogin 3.5.x or later 


version 
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5.2.49 


Type 
Usage 


Arguments 


Description 


Example 


Action 
MatchOption #FormID:FieldID:OptionID [-optional] [-text "text"] [-value "value"] 
#FormlD:FieldID:OptionID 


The ID to be given to the matched option within the field, building from the 
#FormID:FieldID of the associated selection field. The FormID, FieldID and 
OptionIDs must be unsigned integers. The combined #FormID:FieldID:OptionID 
must be unique within the site block. 


-optional 


Specifies that matching this option is not required to successfully match the parent 
field. 


-text "text" 

Specifies the text string for this particular option. 

NOTE: The text is what is displayed to the user. 

-value "value" 

Specifies the value for this particular option. 

NOTE: The value is what is passed to the server when a form is submitted. 


Use the MatchOption command to filter a field based on the presence of a 
particular option. 


An option is an item within a specific combo box or list box. If the option is not 
found, and it is not specified as optional, then the parent field will also fail to match. 


In this example the form named ‘log on’ within the secure Web site www.lotto.com is 
being matched by the application definition. 


# === Logon Application Definition #4 == 
# === Lotto User Initial Logon ==== 


Site Login -userid “Member Log In” -initial 
MatchForm #1 -name “log in” 

MatchDomain “https://site10.Lotto.com” 
MatchField #1:1 -name “Member ID” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchOption #1:3 -name “Secure” -type “text” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 

FocusInput +1:2 -focus “true” 

BooleanInput +1:3 -check “true” 

PressInput 

Endscript 


MatchReferer 


Use with 


Advanced Web application definitions created using the Web Wizard. 


Novell SecureLogin 3.5.x or later 


version 


Type 


Action 
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5.2.50 


Usage 


Arguments 


Description 


Example 


MatchRegex 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


MatchReferer "Referer" 
MatchReferer 


Used inside a site block, MatchReferer is used to filter a site based on a referer. If 
the site referer does not match, the site block fails to match. 


"Referer" 


The site referer which is to be matched. If PageA.htm includes a link to PageB.htm, 
then the referer is "PageA.htm". 


Use MatchReferer inside a Site/EndSite block to match or filter a site based ona 
referer. 


In this example the refering HTML page www.lotto.com/index.html is being matched 
by the application definition. 


# === Logon Application Definition #5 == 
Lotto User Initial Logon ==== 


Site Login -userid “Member Log On” -initial 
MatchForm #1 -name “log on” 

MatchReferer “www.lotto.com/index.htm1” 
MatchDomain “https://site10.lotto.com” 
MatchField #1:1 -name “Member ID” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchOption #1:3 -name “Secure” -type “text” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 

FocusInput +1:2 -focus “true” 

BooleanInput +1:3 -check “true” 

PressInput 

Endscript 


All 


7.0 or later 


Action 

MatchRegex <RegEx> <Input-String> 
<RegEx> 

The regular expression 
<Input-String> 

The string to match against. 


Use the MatchRegex command to test whether a regular expression matches 
against the specified string or not. Can be used inside a Site—EndSite or Dialog— 
EndDialog block for example. 


For more information regarding regular expressions see the Boost C++ Libraries 
Web site (http://www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html) 
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Example 


5.2.51 MatchTitle 


114 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


This example matches against any Web page on the www.google.com domain 
that has a text box, a password box and text somewhere on the page that matches 
against the “Welcome \w+ to Gmail” regular expression (“Welcome Nick to Gmail” 
for example). 

Site “Gmail: Email from Google” 

MatchForm #1 

MatchDomain "www.google.com" 

MatchField #1:10 -type “text” 

MatchField #1:11 -type “password” 

GetText ?PageText 

MatchRegex “Welcome \w+ to Gmail” ?PageText 

EndSite 

MessageBox “Matched” 


Advanced Web application definitions created using the Web Wizard. 
NOTE: -regex parameter is not supported in SecureLogin versions prior to 7.0. 


3.5 or later 


Action 
MatchTitle [-regex] "URL" 
MatchTitle 


Used inside a site block, MatchTitle is used to filter a site based on its title. If the 
site title does not match, the site block fails to match. 


"Title" 

The site title which is to be matched. 

-regex 

You may also use regular expressions to match part of a Title. 


For more information regarding regular expressions see the Boost C++ Libraries 
Web site (http://www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html) 


Use MatchTitle inside a Site block to match or filter a site based on a HTML 
page title. 
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5.2.52 


In this example the HTML page with the title ‘The New York Times > Log In’ within 


Example 


MatchTitle -regex "Times > Log In" 


MatchURL 


Use with 


Advanced Web application definitions created using the Web Wizard. 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


the Web site www.nytimes.com is matched by the application definition. 


# === Initial Login === 

Site Login -userid "nytimes.com #1" -initial 
MatchURL "http://www.nytimes.com/auth/login" 
MatchDomain "www.nytimes.com" 

MatchTitle "The New York Times > Log In" 
MatchForm #1 -name "login" 

MatchField #1:1 -name "USERID" -type "text" 
MatchField #1:2 -name "PASSWORD" -type "password" 
MatchField #1:3 -name "SAVEOPTION" -type "checkbox" -value 
"YES" 

MatchField #1:4 -name "Submit2" -type "submit" 
EndSite 


If the title to match is The New York Times > Log In, then 


NOTE: -regex parameter is not supported in SecureLogin versions prior to 7.0. 


3.5 or later 


Action 
MatchURL [-regex] "URL" 
MatchURL 


Used inside a Site block, MatchURL is used to filter a site based on its URL. If the 
URL doesn't match, the Site block fails to match. 


"URL" 


The site URL which is to be matched. This need not be the URL listed in the 
navigation field of the Web browser as the given page may not have been loaded 
from there. 


-regex 


You may also use regular expressions to match part of a URL, such as the domain 
only. 


For more information regarding regular expressions see the Boost C++ Libraries 
Web site. (http://www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html) : 


Use MatchURL inside a Site block to match or filter a HTML page within a site 
based on its URL. 


The URL can be a complex Web address or a secure Web site. 
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5.2.93 


Example 


MessageBox 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Arguments 


In this example the URL “https://www.nytimes.com/auth/login” is matched. 


# === Initial Login === 

Site Login -userid "nytimes.com #1" -initial 
MatchURL "https://www.nytimes.com/auth/login" 
MatchDomain "www.nytimes.com" 

MatchTitle "The New York Times > Log In" 
MatchForm #1 -name "login" 

MatchField #1:1 -name "USERID" -type "text" 
MatchField #1:2 -name "PASSWORD" -type "password" 
MatchField #1:3 -name "SAVEOPTION" -type "checkbox" -value 
YES 

MatchField #1:4 -name "Submit2" -type "Submit" 
EndSite 


If the URL to match is “http:/Awww.nytimes.com/auth/login?URI=nhttp://", then: 


MatchURL -regex "nytimes.com" 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Action 


MessageBox<Data> [-Background] [-DefaultNo] [-YesNo <?Variable>] [- 
YesNoCancel <?Variable>] 


<-YesNo> 


The -YesNo flag allows the user to select Yes or No within the message box, rather 
than being limited to an OK button only. 


<-YesNoCancel> 


The -YesNoCancel flag allows the user to select Yes, No, or Cancel when a 
message box is displayed. 


<?Variable> 


This runtime variable is required with the -YesNo / -YesNoCancel flag to store the 
result of the user action. 


<-Background> 


When specified, this parameter allows the user to open an application and work in 
that application, without having to respond to the MessageBox. If this parameter is 
not used, the MessageBox remains the active window. In Web applications, you 
must respond to the MessageBox before you can continue with any other work. 


<-DefaultNo> 


This optional parameter is used only with the -YesNo and -YesNoCan-cel flags. 
When the -DefaultNo parameter is set, the No button has the default focus rather 
than the Yes button. 


<Data> 


The text displayed to the user. <Data> can be several strings, variables, or a 
combination of both. 
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Description 


Syntax examples 


Example 1 


Use the MessageBox command to display a dialog box that contains the text 
specified in the <Data> variable. The application definition is suspended until the 
user reacts to this message. The MessageBox can take any number of text 
arguments, including variables (for example, MessageBox "The user " $Username " 
has just logged onto the system"). 


You can set the -YesNo flag when calling a MessageBox. If the -YesNo flag is set, 
the MessageBox prompts the user with a box that has a Yes and a No button, rather 
than an OK button. 


Use a runtime <?Variable> to capture the MessageBox result immediately after the 
flag. The variable value is set to Yes, No, or Cancel. 


MessageBox "Application definition completed successfully" 
MessageBox "Do you wish to continue?" -YesNo ?Result 


MessageBox "Do you wish to continue?" -YesNoCancel ?Result 
-Background -DefaultNo 


Windows application definition 


This example detects the change password dialog box. A message box is displayed 
prompting the user whether or not they would like to change their password, and to 
inform them it was successful. 


# Change Password Dialog Box 
Dialog 

Class #32770 

Title "Change Password" 
EndDialog 


MessageBox -YesNo ?Result "Your password has expired, would 
you like to change it now?" 


If ?Result Eq "Yes" 

Type $Username #1015 

Type $Password #1004 

ChangePassword $Password Random 

Type $Password #1005 

Type $Password #1006 

Click #1 

MessageBox "Password changed successfully" 
Else 

Click #2 

MessageBox "You chose not to change your password" 
EndIf 
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5.2.54 


Example 2 


Multiply 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Arguments 


Description 


Terminal Launcher test application definition 


Use message boxes when troubleshooting application definitions. This example 
displays a message box before each step in the application definition to allow the 
writer to see where the application definition execution is failing. 


The WaitForText cuts off the first character because it finds both Password and 
password, and responds to all password entry points. 


MessageBox "Beginning wait for logon prompt" 
WaitForText "ogin:" 

MessageBox "Logon detected, now entering user name" 
Type $Username 

MessageBox "User name entered, now simulating Enter" 
Type QE 

MessageBox "Enter has been simulated, now waiting for 
password” 

Password"WaitForText "assword:" 

MessageBox "Password detected, now entering password" 
Type $Password 

MessageBox "Password entered, now simulating Enter" 
Type QE 

MessageBox "Sequence completed, the user should now be logged 
on 


All 


3.0 or later 


Variable manipulator 

Multiply <Variable1> <Variable2> [?Result] 
NOTE: You must use integer arithmetic. 
<Variable1> 


The multiplicand, the first argument, is the number multiplied by the second 
argument. Also this argument contains the result if the optional [?Result] argument 
is not passed in. If used without the [?Result] argument, <Variable1> must be a 
Novell SecureLogin variable, either ?Variable1 or $Variable1. Otherwise 
<Variable1> can be any numeric value. 


<Variable2> 


The multiplier, the second argument, is the number by which the first number is 
multiplied. <Variable2> can be a Novell SecureLogin variable or numeric value. 


[?Result] 
Optional, the product, or result of the equation. 


Use to multiply one number by another. You can write the numbers into the 
application definition or use variables. The results can be output to another variable 
or to one of the original numbers. 
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Syntax examples Multiply "1" "2" ?Result 
Multiply ?LoginAttempts ?LoginFailures 
Multiply ?LoginAttempts ?LoginFailures 
Result 
Multiply ?LoginAttempts "3" 
Multiply ?LoginAttempts "3" ?Result 
Example Windows application definition 


This example reads the values of control IDs 103 and 104 into variables. From 
there they are multiplied, and typed into control ID 1. 


ReadText #103 ?Number1 
ReadText #104 ?Number2 


Multiply ?Number1 ?Number2 ?Result 
Type ?Result #1 


5.2.55 OnException/ClearException 


Use with All 


Novell SecureLogin 3.0.4 or later 


version 
Type Flow control 
Usage OnException <Exception Name> Call <SubRoutine> 


ClearException <Exception Name> 
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Arguments 


Description 


Syntax examples 


Example 1 


<Exception Name> 


The name of the exception on which you wish to act. The following exceptions are 
supported: 


+ AAVerifyCancelled: When 8 user cancels the re-authentication process 
(support will depend on the Advanced Authentication product being used). 


+ AAVerifyFailed: When the AAVerify re-authentication command fails. 


+ ChangePasswordCancelled: When 8 user cancels on the Change 
Password dialog. 


+ EnterVariablesCancelled: When a user cancels the automatic variable 
prompt box or the display variables prompt box. 


+ GenerateOTPCancelled: When a user cancels the GenerateOTP dialog. 
* GenerateOTPFailed: When the GenerateOTP command fails. 
+ PickListCancelled: When a user cancels the pick list choice dialog. 


+ RunFailed: When the program specified by the Run command fails to 
launch. 


+ SelectLoginCancelled: When a user cancels the dialog box listing the login 
credential set. 


<SubRoutine> 
The name of the subroutine you want to run when the exception condition is true. 


Use the OnException command to detect when certain conditions are met. 
Currently, this is when Cancel is clicked on either of two dialog boxes. When the 
condition is met, a subroutine is run. Use the ClearException command to 
reset the exceptions value. 


OnException ChangePasswordCancelled Call Display Error 
ClearException ChangePasswordCancelled 


Windows application definition 


In this example the login failed because the user has invalid credentials stored. 
This provides the user with an opportunity to verify their user name and password, 
but what happens if the user clicks Cancel? If the user clicks Cancel, the exception 
is executed and forces the user to enter their credentials. 


# Logon Failed Dialog Box 
Dialog 
Class #32770 
Title "Log on failed" 
EndDialog 
OnException Enter VariablesCancelled Call VariablesCancelled 
DisplayVariables "Please verify your user name and password 
and try again. IT x4532" 
ClearException EnterVariablesCancelled 


Type $Username #1001 
Type $Password #1002 
Click #1 
Sub VariablesCancelled 
OnException EnterVariablesCancelled 
Call VariablesCancelled 
DisplayVariables "You cannot cancel this verification dialog 
box. Please verify your user name and password when prompted 
and click OK to try again." 
ClearException EnterVariablesCancelled 
EndSub 
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Example 2 


Windows application definition 


This example prompts the user to change their password. Novell SecureLogin 
must handle password changes so the password is updated both in the application 
and in the user's 3DES encrypted store (in the directory against their user object). 


# Change Password Dialog Box 
Dialog 

Class #32770 

Title “Change Password” 
EndDialog 


Type $Username #1005 

Type $Password #1006 

OnException ChangePasswordCancelled Call ForceChangePwd 
ChangePassword $Password “Please enter a new password for the 
Human Resources? application. IT x4532” 

Type $Password #1007 

Type $Password #1008 

ClearException ChangePasswordCancelled 


Sub ForceChangePwd 
OnException ChangePasswordCancelled Call ForceChangePwd 
ChangePassword $Password “You must enter a new password 
and cannot Cancel.? 
IT x432” 
Type $Password #1007 
Type $Password #1008 
ClearException ChangePasswordCancelled 
EndSub 
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Example 3 Windows application definition 


This example demonstrates the OnException usage of AAVerifyCancelled and 
AAVerifyFailed. 


# 
# Login - Simple 
# 


Dialog 
Title "Login - Simple" 
Class "#32770" 
Ctrl #1001 
Ctrl #1002 
Ctrl #1 "&Login" 
Ctrl #2 "Cancel" 
Ctrl #1027 "Username:" 
Ctrl #1028 "Password:" 
Ctrl #1009 
EndDialog 
OnException AAVerifyCancelled Call 
CancelSimpleLoginDialogCancelled 
OnException AAVerifyFailed Call 
CancelSimpleLoginDialogFailed 
AAVerify -method "smartcard" 
Type $Username #1001 
Type $Password #1002 
Click #1 
# 
# Cancel the Simple Login Window - AAVerify cancelled 
# 
Sub CancelSimpleLoginDialogCancelled 
Click +2 
EndScript 
EndSub 
# 
# Cancel the Simple Login Window - AAVerify failed 
# 
Sub CancelSimpleLoginDialogFailed 
Click #2 
MessageBox "Your re-authentication failed. Login 
canceled" 
EndScript 
EndSub 
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Example 4 


Windows application definition 


This example demonstrates the OnException usage of GenerateOTPCancelled 
and GenerateOTPFailed. 


# 
# Login - Simple 
# 


Dialog 
Title "Login - Simple" 
Class "#32770" 
Ctrl #1001 
Ctrl #1002 
Ctrl #1 "&Login" 
Ctrl #2 "Cancel" 
Ctrl #1027 "Username:" 
Ctrl #1028 "Password:" 
Ctrl #1009 
EndDialog 
OnException GenerateOTPCancelled Call 
CancelSimpleLoginDialogCancelled 
OnException GenerateOTPFailed Call 
CancelSimpleLoginDialogFailed 
GenerateOTP -mode "AISC-SKI" ?0tpResult 
Type $Username #1001 
Type ?0tpResult #1002 
Click #1 
# 
# Cancel the Simple Login Window - GenerateOTP cancelled 
# 
Sub CancelSimpleLoginDialogCancelled 
Click +2 
EndScript 
EndSub 
# 
# Cancel the Simple Login Window - GenerateOTP failed 
# 
Sub CancelSimpleLoginDialogFailed 
Click #2 
MessageBox "Your generation of your password failed. 
Login cancelled" 
EndScript 
EndSub 
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Example 5 


Windows application definition 


This example demonstrates the OnException usage of 
SelectLoginCancelled. In the following example, we create another 
credential set of Gmail and later create al linked credential set. 


1. Enable the first account for single sign-on. In this example, Gmail. 
2. In the notification area, right-click the Novell SecureLogin icon, then 
select New Login. The Add New Login Wizard Welcome page is displayed. 


3. Select the application for which you want to add another login. In this 
example, Gmail. 


4. Click Next. 


5. Inthe Description field, specify a descriptive name for the login. For example, 
Talk. 


6. Click Finish. 
7. Start the application. 


The <name of the application; in this example, 
www. google . com> login selection dialog box is displayed. 


SecureLogin - www.google.com login selection 


f™ Novell ' 
” SecureLogin, N 


Select the login to use. 


Gmail: Email from Google 


8. Select the required login credential set, then click OK. 


SecureLogin enters the credentials, and you are automatically logged on to 
the application. 


Dialog 
Title "Login - Simple" 
EndDialog 


OnException SelectLoginCancelled Call CannotCancel 
SetPlat Login1 

Type $username #1001 

Type $password #1002 


Sub CannotCancel 

Messagebox "You cannot cancel selecting to use a 
credential set, closing application." 

#Send ALT+F4 to close application 

type \ALT+\|115 

EndScript 
EndSub 
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5.2.56 


Parent/EndParent 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Arguments 


Description 


Windows 


3.5 or later 


Dialog specifier 
ParentEnd 
Parent 

None 


Use the Parent command to begin a parent block in which the statements act 
upon a window's parent. The commands that follow the Parent command function 
identically to commands used in a dialog block; if they equate to false, then the 
application definition ends. 


For example, the command Title in a parent block returns false if the title of the 
parent does not match the one specified in the command. However, if a command 
in a parent block returns a false result, the execution does not skip to the next 
parent block, as it would in a dialog block. Instead, the parent block proceeds to the 
next dialog block or the application definition terminates if no further dialog blocks 
exists. 


The Parent command is particularly useful in applications where the dialog box 
(for example, a login dialog box) is the child of an open window, typically in the 
background. If you are unable to single sign-on to an application after enabling it 
with the wizard, you typically need to specify parent blocks. 


You can also use the Parent command to execute commands on a dialog’s 
parent. For example, it is possible to get an application definition to click a button on 
the parent window. An example is shown below. 


EndParent command Use the EndParent command to terminate a parent block 
and set the subject of the application definition back to the original window. You can 
nest the Parent command, thereby allowing the parent block to act on the parent 
of the parent. 


NOTE: If you use the wizard or try to enable an application and it does not seem to 
work, try using the Parent command. It is able to handle windows that are within 
windows. 
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Example 1 Windows application definition 


This example specifies the dialog box that is used for log on. In this case, the parent 
of the login box has a class of "Centura:MDIFrame". 


# Logon Dialog Box 

Class "Centura:Dialog" 
Ctrl #4098 
Ctrl #4100 
Title "Log on" 
Parent 

Class "Centura:MDIFrame" 
EndParent 


EndDialog 


Type $Username #4098 
Type $Password #4100 
Click #4101 


Example 2 Windows application definition 
This example is used to click a button on the login window’s parent. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


Type $Username #1001 
Type $Password #1002 


Parent 
Click #1 
EndParent 
5.2.57 0 
Use with All 


Novell SecureLogin 3.5 or later (see note under Description below) 


version 

Type Action 

Usage PickListAdd <Display-Text> [<Return-Value>] 
Arguments <Display-Text> 


The text displayed in the pick list for the specified option. 
<Return-Value> 


The value returned from the pick list. If not specified, the return value is the display 
text. 
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Description 


Example 1 


Example 2 


Use the PickListAdd command to allow users with multiple accounts for a 
particular system to choose the account to which they will log on. 


You can also use PickListAdd command to choose from multiple sessions on 
one mainframe account. Use the PickList to build a list of databases, phone 
numbers, or any list from which a user can choose. You can then set variables or 
take action accordingly. 


PickListAdd is always used with the PickListDisplay and is typically also 
used in conjunction with the SetPlat command. 


NOTE: Change in usage from Novell SecureLogin 6.1 on. Setting variables after 
adding them to the list no longer results in the new value appearing in the list. For 
example: 


PickListAdd ?Y 
Set ?Y “Text” 
PickListDisplay ... 


will display the value <not set> 
Java or Windows application definition 


In this example, the user has to pick which of three accounts to use. They pick 
which account they want to use, and Novell SecureLogin switches to that set of 
credentials using the SetPlat command. 


## Logon Dialog Box ## 
Dialog 

Title "Log on" 
EndDialog 
PickListAdd "Account One" "One" 
PickListAdd "Account Two" "Two" 
PickListAdd "Account Three" "Three" 
PickListDisplay ?Account "Please select the account you wish 
to use"-NoEdit 
SetPlat ?Account 
Type $Username #1001 
Type $Password #1002 
Click #1 
## End Logon Dialog Box ## 


Any application definition 


In this example, the application should execute and when Novell SecureLogin runs 
it should display the numbers 0 - 9. 


Set ?Count "0" 
Repeat 10 
PickListAdd ?Count 
Increment ?Count 
EndRepeat 
PickListDisplay ?Count "Please select your option " -NoEdit 
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Example 3 


Java or Windows application definition 


In this example, Novell SecureLogin reads the following window and prompts the 
user with the items in the Other list: 


Password: 


Other: --Make a selzction-- y] 
Ok | Cancel | 


###Logon 
PickListAdd #3 

PickListDisplay ?Database "Select your database" -NoEdit 
SetPlat ?Database 

Type #1 $Username 

Type #2 $Password 

Select ?Database #3 

###End logon## 


5.2.58  PickListDisplay 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Syntax examples 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Action 

PickListDisplay <?Variable> <Display-Text> [-NoEdit] 
<?Variable> 

The output variable for the selected option. 

<Display-Text> 

The description text for the pick list box. 

-NoEdit 

The -NoEdit flag disables the addition of extra variables by the user. 


Use the PickListDisplay command to display the pick list entries built by 
previous calls to PickListAdd. The PickListDisplay command returns the 
result in a <?Variable> sent to the command. 


If the desired entry is not among the displayed entries, the user can enter their 
own data into an edit field at the bottom of the pick list. Set the -NoEdit flag to turn 
this feature off. 


PickListDisplay ?Choice "Please select the account you wish 
to use" 

PickListDisplay ?Choice "Please select the account you wish 
to use" -NoEdit 
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5.2.59 


Example 


Windows example 


In this example, the user has three accounts to this application and wants to pick 
which one to use. They pick which account they want to use and Novell 
SecureLogin uses the SetPlat command to switch to that set of credentials. 


# Logon dialog box 
Dialog 

Class #32770 

Title "Log on" 
EndDialog 
PickListAdd "Account one" "One" 
PickListAdd "Account two" "Two" 
PickListAdd "Account three" "Three" 
PickListDisplay ?Account "Please select the account you wish 
to use" -NoEdit 
SetPlat ?AccountType $Username #1001 
Type $Password #1002 
Click #1 


PositionCharacter 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Arguments 


Description 


Example 


Password Policy application definitions 


3.5 or later 


Action 


POSITIONCHARACTER [NUMERAL] [UPPERCASE] [LOWERCASE] 
[PUNCTUATION] <Position>, [<Position>]. 


[NUMERAL] 

The character at <Position> must be a numeral. 
[UPPERCASE] 

The character at <Position> must be an uppercase character. 
[LOWERCASE] 

The character at <Position> must be a lowercase character. 
[PUNCTUATION] 

The character at <Position> must be a punctuation character. 
<Position> 

The character position in the password. 


Use this command in a password policy application definition to enforce that a 
certain character in the password is a numeral, uppercase, lowercase, or a 
punctuation character. 


You can specify multiple positions. 


The password is not valid unless the first, sixth, and seventh characters are 
uppercase. 


POSITIONCHARACTER UPPERCASE 1,6,7 
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5.2.60 Pressinput 


Use with Advanced Web application definitions created using the Web Wizard. 

Novell SecureLogin 3.5.x or later 

Version 

Type Action 

Usage PressInput [#FormID:FieldID [-press "press"']] 

Arguments PressInput 
Simulates a keyboard enter event. Optionally focusing a given field beforehand. 
#FormID:FieldID 
The ID that was given to the matched field in the Site block using MatchField 
command. The FormID and FieldID must be unsigned integers. 
-press "press" 

Description Simulates pressing the keyboard Enter key. 

Example This example the PressInput command within the application definition is the 


equivalent of clicking the Sign In button on the www.google.com Web site. 


# === Logon Application Definition #2 == 
Google Initial Logon ==== 


Site Login -userid “Google Log On” -initial 
MatchForm #1 -name “log on” 

MatchDomain “www.google.com” 

MatchField #1:1 -name “Email” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchField #1:3 -name “Cookie” -type “check” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 
FocusInput+1:2 -focus “true” 

BooleanInput +1:3 -check “false” 


PressInput 
Endscript 
5.2.61  ReadText 
Use with Terminal Launcher, Windows. This command applies specifically to HLLAPI, 


WinHLLAPI and HLLAPI 16 terminal emulators. 


Novell SecureLogin 3.5 or later 


version 
Type Action 
Windows Usage ReadText <#Ctrl-ID> <?Variable> ReadText [-order] <#Order-ID> 


Terminal Launcher ReadText <?Variable> <Character-Number> <Row-Number> <Column- 
Usage Number> 
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Arguments 


Description 


Syntax examples 


Example 1 


[-order] 


If the control ID's are not constant, utilize the -order argument to instruct Novell 
SecureLogin to type into a control based on the creation order and not the tab 
order. For more information on the -order argument usage, see “Example 4” on 
page 168. 


<#Ctrl-ID> 
The control ID number of the text to read. 
<#Order-ID> 


For Windows application definitions, this parameter specifies which control based 
on the creation order in which to type the text. 


<?Variable> 

The variable that receives the text that is read. 

<Character-Number> 

The number of characters to read. 

<Row-Number> 

The horizontal position number of the first character to read (for example, row). 
<Column-Number> 

The vertical position number of the first character to read (for example, column). 


Use the ReadText command to run in both Windows and Terminal Launcher 
application definitions. While the usage and arguments for the use of ReadText 
with Windows and Terminal Launcher are different, the results of each command 
are the same. 


Windows application definition In a Windows application definition, the 
ReadText command reads the text from any given <#Ctrl-ID>, and sends it to the 
specified variable. For this command to function correctly, the <#Ctrl-ID> must be 
valid. 


Terminal Launcher application definition In a Terminal Launcher application 
definition, the ReadText command reads a specified number of characters, 
starting at the <Row-Number>, and sends those characters to the specified 
<Variable>. The ReadText command will not work with Generic or Advanced 
Generic emulators, it only works with HLLAPI and some DDE emulators. For 
Generic or Advanced Generic emulators, use the If -Text or Gettext commands. 


For more information, see Section 5.2.40, “If/Else/Endlf,” on page 99 and 
Section 5.2.36, “GetText,” on page 97. 


ReadText #301 ?Text 
ReadText ?Text 4 6 


HLLAPI emulator 

Readtext ?result "א"‎ "Y" "2" 

X = The number of characters to read. 

Y= The row from which the characters are read. 


Z= The column from which the characters are read. 
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Example 2 


Example 3 


Example 4 


Example 5 


Windows script 
ReadText #1004 ?result 
Windows application definition 


The same title and class appear in the error message dialog box when a user fails 
to log on. 


This example distinguishes between errors and provides users with more specific 
information, rather than a general message stating their username and password 
is incorrect, or the account is locked. In this case, the example reads the error 
message, clicks OK, and prompts the user with a customized message. 


# Logon Failed Message 
Dialog 

Class #32770 

Title "Log on failed" 
EndDialog 


ReadText #65535 ?ErrorMsg 
Click #1 
If "Invalid Username" -In ?ErrorMsg Display-Variables 
"Please verify your Username and try again." $Username 
Type $Username #1001 
Type $Password #1002 
Click #1 
EndIf 
If "Invalid Password" -In ?ErrorMsg Display-Variables 
"Please verify your Password and try again." $Password 
Type $Username #1001 
Type $Password #1002 
Click #1 
EndIf 
If "Account locked" -In ?ErrorMsg MessageBox "Your account 
is locked. Please contact the IT help- desk on x4532." 
EndScript 
EndIf 


Windows application definition 


This example reads the text from a control ID and sets the database variable so 
the user is not prompted to set the variable. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title "Log on" 
EndDialog 
ReadText #15 ?Database 
If -Exists $Database 
Else 

Set $Database ?Database 
EndIf 
Type $Username #1001 
Type $Password #1002 
Type $Database #1003 
Click #1 


Terminal Launcher application definition 


This example reads a message in a trminal emulator and displays the message in 
a user friendly format. 


ReadText ?Message 30 24 2 
MessageBox ?Message 
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5.2.62 


Example 6 


RegSplit 


Windows application definition 


This example reads the text from a control defined by its creation order and sets 
the database variable so the user is not prompted to set the variable. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 
ReadText -order #5 ?Database 
If -Exists $Database 
Else 
Set $Database ?Database 
EndIf 
Type $Username #1001 
Type $Password #1002 
Type $Database #1003 
Click #1 


When using regular expressions with the RegSplit command, ensure that any regular expressions 
comply with the syntax rules detailed under Section 4.3.8, “Regular Expressions,” on page 49. 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


All 


3.5 or later 


Action 

RegSplit <RegEx> <Input-String> [<Output-String1> [<Output-String2>]...] 
<RegEx> 

The regular expression. 

<Input-String> 

The string that to split. 

<Output-String1> 

The first sub-expression. 

<Output-String2> 

The second sub-expression. 


Use the RegSplit command to split a string using a regular expression. <Output- 
String1> and <Output-String2> contain the first and second sub-expressions 
respectively. 


For more information regarding regular expressions see: 


www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html (http:// 
www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html) 


For information regarding Microsoft regular expression usage, search the 
Microsoft MSDN Library at: 


http://msdn2.microsoft.com/en-us/library/default.aspx (http:// 
msdn2.microsoft.com/en-us/library/default.aspx) 
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Example 1 Windows application definition 


This example copies text from control ID 301 to the ?Text variable. The RegSplit 
command is then used to strip the user name details out of the text that was read. 
The platform is set to that user name, and the correct password is entered by 
Novell SecureLogin. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title "Log on" 
EndDialog 
ReadText #65535 ?Text 
RegSplit "Please enter the password for (.*) account" ?Text 
?UserSetPlat ?User 
Type $Username #1001 
Type $Password #1002 
Click #1 


Example 2 How to handle regsplit exception with OnException 


# Logon Dialog Box 
Dialog 
Title "Untitled - Notepad" 
EndDialog 
Set ?Url "Oneabc" 
Type ?Url 
Type \n 
# Create exception handler 
OnException RegSplitFailed Call RegSplitError 
# Provide suspicious regular expression, note the "\)" below 
RegSplit "(.*\)abc(.*)" ?Url ?Lhs ?Rhs 
StrCat ?Url ?Lhs ", " ?Rhs 
MessageBox ?Url 
ClearException RegSplitFailed 
Sub RegSplitError 
# print out RegSplitReturnCode 
Type "RegSplitError: " 
Type ?RegSplitReturnCode 


Type \n 
EndScript 
EndSub 
Open text example #?InputString: "This is a long string with a few components 
in it" 
Command RegSplit "This(.*)a long(.*)with(.*)components(.*)" 
?InputString ?First ?Second ?Third ?Fourth 
Result ?First = "is", ?Second = "string", ?Third = "a few", ?Fourth 
= "in it" 


5.2.63 ReLoadPlat 


When an application first presents a login screen, Novell SecureLogin displays a message prompting 
the user to select an appropriate platform from a list. Once selected, Novell SecureLogin enters the 
chosen platform's credentials into the application and submits them. 
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Resolving the issue of re-entering user ID details 


If log on fails due to incorrect credentials, Novell SecureLogin prompts the user to change their 


credentials. Novell SecureLogin does not retain the platform details and prompts the user to re-enter 


the information. This could result in the user changing the wrong credentials if they select the 
incorrect platform. 


The SetPlat, ReLoadPlat and ClearPlat commands resolve this issue. ReloadPlat sets the current 


platform to the one which was last chosen (for the given application) or, if a platform was not 
previously selected, the command will leave it unset. 


See also Section 5.2.77, “SetPlat,” on page 149 and Section 5.2.11, “ClearPlat,” on page 71. 


Use with Startup, Terminal Launcher, Web, or Windows 


Novell SecureLogin 3.5 or later 


version 
Type Action 
Usage Use the ReLoadPlat command at: 

* Log on. Before the user first logs onto the application, call ReLoadPlat. This 
prevents the user from having to reselect a platform after a failed log on. 

+ Failed log on. Call ReLoadPlat to reselect the platform that contained the 
incorrect credentials. This gives the user an opportunity to change the 
credentials using a ChangePassword or a DisplayVariables command. 

Arguments None 
Description Use to set the current platform to the last one chosen by the application definition 


or, if a platform is not chosen, leaves the platform unset. 
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Example Windows application definition 


# ==== BeginSection: Application startup ==== 
Dialog 

Class "#32770" 

Title "Password Test Application" 


EndDialog 

ClearPlat 

# ==== EndSection: Application startup ==== 
# ==== BeginSection: Log on ==== 

Dialog 


Class "#32770" 

Title "Log on" 

Ctrl #1001 
EndDialog 
ReLoadPlat 
SetPrompt "Username =====> 
"Type $Username #1001 
SetPrompt "Password =====> 
"Type $Password #1002 
SetPrompt "Domain =====> 
"Type $Domain #1003 
Click #1 
# ==== EndSection: Log on ==== 


HH ==== BeginSection: Log on successful ==== 
Dialog 
Class "#32770 
"Title "Log on successful" 
EndDialog 
ClearPlat 
Click #2 
# ==== EndSection: Log on successful ==== 


Example (continued) # ==== BeginSection: Log on failure ==== 
Dialog 
Class "#32770" 
Title "Log on failure" 
EndDialog 
Click #2 


ReLoadPlatOnException ChangePasswordCancelled Call Change- 
Cancelled 

ChangePassword $password 

ClearException ChangePasswordCancelled 

Type -raw \Alt+F 


Type -raw L 
# ==== EndSection: Log on failure ==== 
# ==== BeginSection: Change credentials cancelled ==== 
Sub ChangeCancelled 
ClearPlat 
EndScriptEndSub 
# ==== EndSection: Change credentials 
Cancelled === 


5.2.64 Repeat/EndRepeat 


Use with All 


Novell SecureLogin 3.5 or later 
version 
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Type 
Usage 


Arguments 


Description 


Syntax examples 


Example 


Action 
Repeat [Loop#] EndRepeat 
[Loop#] 


The number of times the repeat application definition block is repeated. If not 
specified, the repeat continues indefinitely unless broken by other commands 


Use the Repeat command to establish an application definition block similar to 
the If command. The repeat block is terminated by an EndRepeat command. 
Alternatively, you can use the Break or EndScript commands to break out of 
the loop 


Repeat 
Repeat 3 


Terminal application definition 


This example uses the Repeat command to watch the screen for the messages 
and responds accordingly. You can use the Break command to jump to the next 
repeat loop in the application definition. 


# Initial System Log on 
WaitForText "login:" 
Type $Username 
Type @E 
WaitForText "password:" 
Type $Password 
Type @E 
Delay 500 
#Repeat loop for error handling 
Repeat 
#Check to see if password has expired 
If -Text "EMS: The password has expired." 
ChangePassword 
#Password 
Type $Password 
Type @E 
Type $Password 
Type @E 
EndIf 
#User has an invalid Username and / or # Password stored. 
If -Text "Log on Failed" 
DisplayVariables "The username and / or password stored by 
SecureLogin is invalid. Please verify your credentials and 
try again. IT x453." 
Type $Username 
Type QE 
Delay 500 
WaitForText "password:" 
Type $Password 
Type QE 
Delay 500 
EndIf 
# Account is locked for some reason, possibly inactive. 
If -Text "Account Locked" 
MessageBox "Your account has been locked, possibly due to 
inactivity for 40 days. Please contact the administrator on 


# Main Menu, user has logged on successfully. 
If -Text "Application Selection" 

Break 
EndIf 

Delay 100 

EndRepeat 
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5.2.65 


RestrictVariable 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Arguments 


Description 


All 


3.5 or later 


Action 

RestrictVariable <Variable-Name> 
<Password-Policy> 

<Variable-Name> 

The name of the variable to restrict. 
<Password-Policy> 

The name of the policy to enforce on the variable. 


Use the RestrictVariable command to monitor a variable and enforce a 
specified password policy on the variable. Any variable specified must match the 
policy or it is not saved. 


When restricting variables to policies, if you are making a tighter policy than is 
already in place, and you restrict a variable that does not match the policy today, 
then the user cannot save it the first time. This is because when Novell 
SecureLogin detects there is no saved credential, a user who has a password of 6 
characters today cannot save it if the policy restricts the $Password variable to 8 
characters and 2 numbers. 


“Example 2” on page 139 works around this by restricting a new password variable 
(?NewPwa), instead of restricting the $Password variable. The user can store their 
existing password when Novell SecureLogin prompts for the credentials first time, 
and enforces the stronger password policy when the password expires in x days. 


You can restrict any variable using a password policy, not just a $Password. You 
can also use RestrictVariable to make sure other variables are entered in the 
correct format. For example, you can enforce that $Username is always lowercase 
or $Database is 6 characters and no numbers. 
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Example 1 


Example 2 


Windows application definition 


This example uses the application definition to restrict the $Password variable to 
the Finance password policy. The user's password must match the policy when they 
first save their credentials. When the password requires changing, the application 
definition generates a new password randomly based on that policy (no user 
intervention is required). 


# Set the password to use the Finance password policy 
RestrictVariable $Password FinancePwdPolicy 


#Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


Type $Username #1001 
Type $Password #1002 


#Change Password Dialog Box 


Dialog 
Class #32770 
Title "Change Password” 
EndDialog 
Type $Username #1015 
Type $Password #1004 
ChangePassword $Password Random 
Type $Password #1005 
Type $Password #1006 
Click #1 


Windows application definition 


This example uses the application definition to restricts the ?NewPwd variable to 
the Finance password policy. When the application starts for the first time and 
prompts the user to enter their credentials, then their current password 
($Password) is saved and used. 


When the password expires, the password policy is enforced on any new password. 
This is a way to enforce tougher password policies (than are currently in place) 
when you cannot guarantee all existing passwords meet the new policy. 


# Set the password to use the Finance password policy 
RestrictVariable ?NewPwd FinancePwdPolicy 
# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 
Type $Username #1001 
Type $Password #1002 
Click #1 
# Change Password 
Dialog Box 
Dialog 
Class #32770 
Title "Change Password" 
EndDialog 
Type $Username #1015 
Type $Password #1004 
ChangePassword ?NewPwd Random 
Type ?NewPwd #1005 
Type ?NewPwd #1006 
Set $Password ?NewPwd 
Click #1 
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5.2.66 Run 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Example 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Action 

Run <Command> [<Arg1> [<Arg2>] ...] 

<Command> 

The full path of the program to execute. 

<Arg1>, <Arg2> 

An optional list of arguments and switches for the command. 


Use the Run command to launch the program specified in <Command> with the 
specified optional [<Arg1> [<Arg2>] ...] arguments. 


The application definition does not wait for the launched program to complete. 
Startup application definition 

This example prompts the user to start the Finance System. 

If they click: 


* Yes, the Run command is used to start the application with the necessary 
switches. 


+ No, a message box is displayed, and the application is not started. 


MessageBox "Would you like to connect to the Finance System?" 
-YesNo ?Result 
If ?Result Eq "Yes" 
foe "C:\Program Files\HRS\Finance.exe" "/DB:HRS" "/Debug" 
Else 
MessageBox "You have chosen not to run the Finance System. 
Please do so manually." 


EndScript 
EndIf 
5.2.67 RunEX 
Use with Startup, Terminal Launcher, Web, or Windows 
Novell SecureLogin version 7.0.3 or later 
Type Action 
Usage RunEx [-show <state>] [-position <coord>] [-size 
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<dimensions>] -cmd "executablepath" [arg1[ argN]] 
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Use with Startup, Terminal Launcher, Web, or Windows 


Arguments -show <state> 


state is a variable or value that represents a window 
state. For more information about the values, see 
ShowWindow function. 


NOTE: If the state cannot be evaluated to a valid state, 
then the default value is NORMAL. 


-position <coord> 


coord is a variable or value that represents screen 
position in pixels from the top left of the window. 


-size <dimensions> 


dimensions is a variable or value that represents 
width in pixels. 


<Arg1>, ....<ArgN> 


An optional list of arguments and switches for the 
command 


Description RunEX executes a function in the hidden mode based 
on the options the user provides. 


Example For Example: 


+ RunEx -show maximize -cmd cmd.exe 
+ RunEx -position 50,50 -cmd cmd.exe 
+ RunEx -size 800,900 -cmd cmd.exe 


* RunEx -show hide -cmd <application> 
<arg1> <arg2> 


5.2.68 Select 


Use with Java, Advanced Web, Windows 


Novell SecureLogin 6.1 or later 


version 
Type Action 
Usage Select <Text of Item to select> [<#Ctrl-ID>] 
Arguments <Text of Item to select> 
The text item that you want Novell SecureLogin to select in the list box. 
<#Ctrl-ID> 
When multiple list boxes are found, this specifies which list box to address. 
Description Use the Select command to select entries from a combo or list style control. 
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Examples 


Use with 


This example picks an item from the session combo or list control: 


Select ?session #1 


This example selects a tab within another tab control. When one tab control is 
contained within another, the tab selection order is irrelevant. 


Select “Quick Connect” #70 
Select “Connection” #69 


This example selects a cell from within a table 


Select “[0,0]” #1 
If -text “User” #1 
Select “[0,1]” #1 
Type $Username #1 
Endif 


SelectListBoxltem 


Advanced Web application definitions 


Novell SecureLogin 3.5 or later 


version 


Type 
Usage 


Arguments 


Description 


Example 


Action 
SelectListBoxltem :<Item text of selection> <#Ctrl-ID> [-multiselect] 
<Item text of selection> 


The text item that you want SecureLogin to select in the list box. it can be a variable 
or a string. 


<#Ctrl-ID> 
Must be provided. 
<-multiselect> 


Used to select multiple list box entries by using a subsequent 
SelectListBoxItem command. 


Use the SelectListBoxItem command to select entries from a list box. 


For instructions on determining <#Ctrl-IDs>, see Section 5.2.22, “DumpPage,” on 
page 85. 


If "ERROR: The credentials supplied were invalid. Please try 
again." -In ?Text 

SelectListBoxItem "Find Context" #1 

Type ?SysUser #1 

Type $Password #2 

MessageBox "If logon continues to fail, please logout of the 
computer and back 

in, retry, and report it to your SecureLogin administrator." 
EndScript 

EndIf 
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5.2.71 


SelectOption 


Use with Advanced Web application definitions. 


NovellSecureLogin 3.5.x or later 


version 
Type Action 
Usage SelectOption #FormID:FieldID:OptionID -select <true|false> 
or 
SelectOption #FormID:FieldID -clear 
Arguments #FormlD:FieldID:OptionID 
The ID that was given to the matched option in the Site block using the 
MatchOption command. The FormID, FieldID, and OptionID must be unsigned 
integers. 
-select "select" 
Selects or deselects a specific option. 
"select" is a Boolean value, either "true" or "false". 
-clear 
Deselects all options for the given control. 
Description Use the SelectOption command to select or deselect options within a list box or 
combo dialog box. 
Example This example clears the selection in the option list and selects option 2 only. 


SelectOption #1:3 -clear 
SelectOption #1:3:2 -select true 


SendEvent 


Use with All 

Novell SecureLogin 7.0 

Version 

Type Action 

Usage SendEvent <Windows Handle> <Event Specifier> 
Arguments <Windows Handle> 


A valid windows handle. This should be a local variable with the handle initialised 
via a call to GetHandle. Alternatively, it is possible to broadcast the event by 
using the Windows constant HWND_BROADCAST. 


<Event Specifier> 


See Section 5.2.24, “Event/Event Specifiers,” on page 86 for the applicable 
conditions. In addition, a new custom single sign-on event can be used, 
SSO_NOTIFY. 
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Description 


Example 1 


Example 2 


5.2.72 SendKey 


Use with 


Novell SecureLogin 
Version 


Type 
Usage 


Arguments 


Description 


Example 


Use the SendEvent command with constants: 
+ HWND_BROADCAST to send an event to all windows 
* SSO_NOTIFY to send a custom single sign-on event 
Send WM_SETFOCUS using a captured handle 
Event WM_SETFOCUS 


GetHandle ?handle 
SendEvent ?handle WM_SETFOCUS 


Broadcast the custom SSO_NOTIFY event 
Event SSO_NOTIFY 


SendEvent HWND_BROADCAST SSO_NOTIFY 


Terminal Launcher 


3.5 or later 


Action 

SendKey <Text> 

<Text> 

The text typed into the emulator screen. 


Use the SendKey command to work only with Generic and Advanced Generic 
emulators. You can use the SendKey command in the same manner as the Type 
command. Generally, the Type command is the preferred command to use. The 
Type command places the text into the clipboard, and then pastes it into the 
emulator screen. The SendKey command enters the text directly into the emulator 
screen. 


Using the Type Command: Variables do not work with the SendKey command. If 
you want to use variables, use the Type command. 


The Type command has many special functions, and some you can use with the 
SendKey command. For more information, see Section 5.2.92, “Type,” on 
page 165 and Chapter 7, “Reference Commands and Keys,” on page 179. 


Terminal Launcher application definition 
The example sends the username and password to the terminal emulator. 


#Send User Name 
SendKey "DJones" 
SendKey "AN" 
#Send Password 
SendKey "Hu7%f" 
SendKey "\N" 
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5.2.73 Set 


Use with All 


Novell SecureLogin 3.5 or later 


version 

Type Action 

Usage Set <Variable> <Data> 

Arguments <Variable> 
The variable to which the data is being assigned. 
<Data> 
The text or variable read from and assigned to the variable. If the data argument 
contains a ? then it must be escaped (\?), for example: 
Set ?Message “\?Username” 

Descriptions Use the Set command to copy the value of <Data> into <Variable>. The <Data> 
can be any text or another variable, whereas the <Variable> must be either a 
?Variable or $Variable. 

Example 1 Windows application definition 


This example uses the application definition to set a ?RunCount variable to count 
the number of times the application is run. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


If ?RunCount Eq <NOTSET> 
Set ?RunCount "1" 
Else 
Increment ?RunCount 
EndIf 


Type $Username #1001 


Type $Password #1002 
Click #1 
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Example 2 Windows application definition 


This example uses the application definition to set the ?NewPwd to the stored 
$Password variable. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


Type $Username #1001 
Type $Password #1002 
Click #1 


# Change Password Dialog Box 
Dialog 

Class #32770 

Title "Change Password" 
EndDialog 


Type $Username #1015 
Type $Password #1004 
ChangePassword ?NewPwd Random 
Type ?NewPwd #1005 
Type ?NewPwd #1006 
Set $Password ?NewPwd 

Click #1 


Example 3 Windows application definition 


This example uses the application definition to read the value of control ID 15 and 
sets the $Database variable so the user does not have to set the variable. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


ReadText #15 ?Database 
If -Exists $Database 
Else 


Set $Database ?Database 
EndIf 


5.2.74 SetCheckBox 


Use with Advanced Web, Windows 


Novell SecureLogin 3.5 or later 


version 

Type Action 

Usage SetCheckBox <Item Number> <Option> 
Arguments <Item Number> 


The check box in reference to the number of check boxes found. 
<Option> 


Specifies the status of the check box as Checked or Unchecked. 
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5.2.75 


Description 


Example 


SetCursor 


Use with 


Novell SecureLogin 


version 
Type 
Usage 1 
Usage 2 


Arguments 


Use the SetCheckBox command to select or clear a check box. 


MessageBox "Scroll down to see the 'Search Language' section 
with the check boxes then click OK"setcheckbox #1 "checked" 
setcheckbox #2 "checked" 
setcheckbox #3 "checked" 
setcheckbox #4 "checked" 
setcheckbox #25 "checked" 
setcheckbox #26 "checked" 
setcheckbox #27 "checked" 
MessageBox "Did it select the first four languages and 
Norwegian, Polish and Portuguese languages" -yesno ?advweb 
if ?advweb eq yes 
set ?cmd37 "SetCheckBox command worked" elseset ?cmd37 
"SetCheckBox failed" 
endifset 
checkbox #1 "unchecked" 
setcheckbox #2 "unchecked" 
setcheckbox #3 "unchecked" 
setcheckbox #4 "unchecked" 
setcheckbox #26 "unchecked" 
setcheckbox #27 "unchecked" 
MessageBox "Did it clear all languages except Norwegian" 
yesno ? 
advweb2 
if ?advweb2 eq yes 
set ?cmd38 "SetCheckBox command worked" 
else 
set ?cmd38 "SetCheckBox failed" 
endif 


Terminal Launcher (only available in HLLAPI and some DDE emulators) 


3.5 or later 


Action 

SetCursor <Screen-Position> 

SetCursor <X Co-ordinate> <Y Co-ordinate> 
<Screen-Position> 

The position on the screen to move the cursor. 
<X Co-ordinate> 


The horizontal coordinate. When specified, a row or column conversion is carried 
out before the cursor is set to the position. 


<Y Co-ordinate> 


The vertical coordinates. When specified, a row or column conversion is carried 
out before the cursor is set to the position. 
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5.2.76 


148 


Description 


Syntax examples 


Example 


SetFocus 


Use with 


Novell SecureLogin 
version 


Type 
Arguments 


Description 


Example 


Use the SetCursor command to set the cursor to a specified <Screen-Position> 
or <X Co-ordinate> <Y Co-ordinate>. 


The position is noted by a number greater than O (zero), for example, 
SetCursor 200. Terminal Launcher displays an error message if the screen 
position is invalid. 


SetCursor 200 
SetCursor 100 500 
Terminal Launcher application definition 


This example sets the cursor to the correct position, and then you enter 
credentials. 


SetCursor 200 
Type $Username 
Type @E 
Type $Password 
Type @E 


Java and Windows 


3.5 or later 


Action 

<#Ctrl-ID> 

The ID number of the control to which the keyboard focus is directed. 

Use the SetFocus command to set the keyboard focus to a specified control ID. 
A valid control ID is required for the SetFocus command to function correctly. 
Windows application definition 


This example sets the focus to the username field (#1001). The username is typed 
and a tab stop is simulated, and then the password is typed and pressing Enter is 
simulated. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


SetFocus #1001 
Type $Username 
Type \T 
Type $Password 
Type \N 
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5.2.77 


SetPlat 


Use with 


Novell SecureLogin 
version 


Type 
Usage 1 
Usage 2 


Arguments 


Description 


All 


3.5 or later 


Action 

SetPlat <Application-Name> 

SetPlat <RegEx> <Variable> <#Ctrl-ID> 
<Application-Name> 

Application name from which to read the variables. 
<RegEx> 

Regular expression to use as application name. 
<Variable> 


Use a previously set ?Variable, for example, using a PickList (see Section 5.2.57, 
“PickListAdd,” on page 126). 


<HCtrl-1D> 


The control ID number of the regular expression. For information regarding regular 
expressions see: 


www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html 


By default, variables are stored directly against the platform or application on 
which you have Novell SecureLogin enabled. For example, if you enable 
Groupwise.exe, the Groupwise credentials are stored against the Groupwise.exe 
platform. 


SetPlat sets the platform or application from which variables are read and saved if 
you have: 


+ Multiple accounts (for example, your own log on and an admin log on) 
accessing the same platform or application. 


+ Multiple platforms or applications using a common set of credentials? 


Other uses of SetPlat include: 


+ Configuring application1 to read it's $Username and $Password from 
application2. This saves a user from entering the credentials twice and 
having to remember to update them in both locations when they change, and 
so on. 


+ Configuring application1, application2, and application3 to read the users 
credentials from Platform Common. This results in a single store of common 
credentials which you only need to update once. 
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Example 1 


Web application definition 


The following is a standard dialog box for accessing a password-protected site 
using Netscape Navigator. 


Username and Password Required x| 


Ente: username for Control Panel a: 
wa. serversystems com: 


User Name: i 
Password: | 


Cancel | 


When you specify the Title, Class, User Name, and Password fields for this dialog 
box they are always the same. If you stored the user name and password against 
this platform without using the SetPlat command, the same user name and 
password for www.serversystems.com is entered to log on to any site (and are 
obviously invalid for any other site). 


However, the previous dialog box always contains the name of the Web site to 
which to log on. You can use this name as the unique identifier in order to set a 
new platform and to save the log on credentials. 


Using a dialog block with a SetPlat statement The solution is to use a dialog 
block with a SetPlat statement such as: 


Dialog 
Ctrl #330 
Ctrl #214 
Ctrl #331 
Ctrl #1 
Ctrl #2 
Title "Username and Password Required" 
SetPlat #331 "Enter username for (.*) at (.*):" 
EndDialog 
Type $Username #214 
Type $Password #330 
Click #1 


The power of this application definition is the line: 


SetPlat #331 "Enter username for (.*) at (.*):" 


This reads the line from dialog control ID 331, enters the user name for Control 
Panel at www.serversystems.com, and applies the regular expression to this text. 
Regular expressions are a way of manipulating text strings, however, for most 
purposes a few very basic commands work. 


For information regarding regular expressions see: 


www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html (http:// 
www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html) 


When the user has run the application definition, they will see the user name and 
password saved as www.serversystems.com. The text matched inside the 
brackets then becomes the symbol application. If a dialog <#Ctrl-ID> is not 
specified, the symbol application is unconditionally changed to the application 
specified in <RegEx>. An unconditional SetPlat command is only valid if 
specified before Dialog/EndDialog statements. 
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5.2.78 


Example 2 


SetPrompt 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Windows application definition 


This example displays a pick list and sets a new platform so multiple users can log 
on to the application. In this case, SetPlat creates a new platform called Default 
User, Global Administrator, or Regional Administrator, and the respective 
$Username and $Password is saved there. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


PickListAdd "Default User" 

PickListAdd "Global Administrator" 

PickListAdd "Regional Administrator" 

PickListDisplay ?Choice "Please select the account you wish 
to use"-NoEdit 

SetPlat ?Choice 

Type $Username #1001 

Type $Password #1002 

Click #3 


All 


3.5 or later 


Action 
SetPrompt <Prompt-Text> 
<Prompt-Text> 


The customized text prompt displayed in the Enter Novell SecureLogin Variables 
dialog box. 


Use the SetPrompt command to customize the text in the Enter Novell 
SecureLogin Variables dialog boxes. These dialog boxes are used to prompt the 
user for new variables. You can also use the DisplayVariables command to 
customize the prompt text in the dialog box (for previously stored variables). 


For more information, see Section 5.2.20, “DisplayVariables,” on page 82. 


NOTE: Positioning of the SetPrompt command is crucial. Position it before the 
first usage of each variable to name that variable, and apply the final Setprompt to 
the text displayed at the top of the prompt screen. 
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Example 1 


Example 2 


Windows application definition 


This example replaces the default text prompt in the Enter Novell SecureLogin 
Variables dialog box, and places the SetPrompt command at the bottom of the 
application definition. 


# Logon Dialog Box 
Dialog 

Class #32770 

Title "Log on" 
EndDialog 

Type $Username #1001 

Type $Password #1002 

Click #1 
SetPrompt "Please enter your user name and password for 
accessing the Human Resources system. These credentials will 
be remembered by SecureLogin and you will be automatically 
logged on in future. IT Help Desk x4532" 


Windows application definition 


This example replaces the text prompt next to any variable entry field in the Enter 
Novell SecureLogin Variables box and places the SetPrompt command 
immediately before the variable in the application definition. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 
SetPrompt "Enter Username==>" 
Type $Username #1001 
SetPrompt "Enter Password==> 
"Type $Password #1002 
Click #1 
SetPrompt "Please enter your user name and password for 
accessing the Human Resources system. These credentials will 
be remembered by SecureLogin and you will be automatically 


logged on in future. IT Help Desk x4532" 
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5.2.79 


5.2.80 


-SiteDeparted 


Use With 


Novell SecureLogin 
version 


Type 
Argument 


Description 


Example 


Site/Endsite 


Use with 


Novell SecureLogin 
Version 


Type 


Usage 


Web 


3.5 or later 


Action 
SiteDeparted is a conditional variable. 


Use the SiteDeparted variable in Web scripts to see if the current document is still 
active when used as part of an If statement. 


The following example checks if the user has navigated away from the current Web 
site or not. 


If the users have navigated away from the Website, it informs the users and exists the 
script. 


If -SiteDeparted 
MessageBox "Script terminated, we have left the web-site" 


EndScript 
EndIf 


Advanced Web application definitions created using the Web Wizard. 


3.5.x or later 
Action 


Site ["Name" [-userid "userid"] [-initial|-subsequent|-recent timeout] [- 
nonexclusive]] 
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Arguments 


Description 


Example 1 


Site 


The Site/EndSite commands are used to match a particular site given a set of 
filters. Site/EndSite usage is much the same as the Dialog/EndDialog commands 
found in the windows scripting commands. 


"Name" 


Name is a static string used to denote the site being matched. The Name cannot 
be a variable and the same value can be used by multiple Site commands to 
specify a match for the same site under differing conditions. 


-userid "userid" 

Specifies the default set of credentials to be used for this site block. 
NOTE: "userid" must be a static string. 

-initial 

Specifies that this site block will only match the first time. 
-subsequent 


Specifies that this site block will only match after an initial match has already been 
made. 


-recent timeout 


Specifies that this site block will only match if a previous match was made within 
the given timeout period. 


Timeout is given in milliseconds. 
-nonexclusive 


Specifies that even if this site block matches, other scripts and wizards will not be 
prevented from running. 


Slte/EndSite begins and ends an application definition, in place of Dialog/ 
EndDialog. 


The Site/EndSite commands have been added to allow for much finer control of 
Web site matching. No longer is a URL all that can be matched on. Detailed 
information of the loaded Web site can now be matched upon and used to execute 
blocks of scripting commands. 


Site/EndSite blocks are used to define all the parameters Novell SecureLogin 
would expect to find on a Web page to run the application definition. 


'Match' commands can be used to filter a given site. If one of the contained match 
commands fails to match, then the site block fails to match as a whole. 


This simple example would locate the Web site www.mybank.com. 


# === My Bank Initial Logon === 

Site “www.mybank.com” -userid “My Logon Credentials” 
-initial 

EndSite 
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5.2.81 


Example 2 


StrCat 


Use with 


Novell SecureLogin 
Version 


Type 
Usage 


Arguments 


Description 


This simple example would locate the Web site www.google.com, locate the login 
form and log on to the user’s account using the user’s e-mail address, account 
number and password. 


# === Logon Application Definition #2 == 
# === Google Initial Logon ==== 
H== === SaaS SSS S SaaS SSS SSS => === — == 


Site Login -userid “Google Log On” -initial 
MatchDomain “www.google.com” 

MatchField #1:1 -name “Email” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchField #1:3 -name “Cookie” -type “check” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 
FocusInput+1:2 -focus “true” 

BooleanInput #1:3 -check “false” 

PressInput 

Endscript 


All 


3.5 or later 


Action 

StrCat <Variable> <Input-String1> <Input-String2> 
<Variable> 

The variable to which you want a result saved. 
<Input-String1> 

First data string or variable. 

<Input-String2> 

Second data string or variable. 


Use the StrCat command to append the second data string to the first data 
string. For example, StrCat ?Result "SecureRemote " "$Username". 


In this case "$Username" is "Tim", and the variable "?Result" now contains the 
value "SecureRemote Tim". 
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Example Windows application definition 


This example reads the user name from #1001 into ?Username and uses the 
StrCat command to join the user name onto the password. The result is a 
LoginID, which Novell SecureLogin uses to log on to the system. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


ReadText #1001 ?Username 
StrCat ?LoginID $Username $Password 


Type ?LoginID #1002 
Click #1 


5.2.82 StrLength 


Use with All 


Novell SecureLogin 3.0.4 or later 


version 
Type Variable manipulator 
Usage StrLength <Destination> <String> 
Arguments <Destination> 
The output variable. Also the input variable if no source is specified. 
<String> 
The string whose length you want to measure. 
Description Use the StrLength command to count the number of characters in a variable 
and output that value to the destination variable. 
Example Windows application definition 


This example reads the password from #301 and then uses StrLength to count the 
number of characters. If it is less that 4, an error message is displayed. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


ReadText #301 ?Password 
StrLength ?Length $Password 
If ?Length Lt "4" 


MessageBox "Password is too short" 
EndIf 


5.2.83 StrLower 


Use with All 
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5.2.84 


Novell SecureLogin 
Version 


Type 
Usage 


Arguments 


Description 


Example 


StrUpper 


Use with 


Novell SecureLogin 
version 


Type 


Arguments 


3.0.4 or later 


Variable manipulator 

StrLower <Destination> [<Source>] 

<Destination> 

The output variable. Also the input variable if no source is specified. 
[<Source>] 


The input variable. If not specified, Novell SecureLogin reads the destination 
variable, makes the necessary changes, and writes over the variable. 


Use the Str Lower command to modify a variable so that all the characters are 
lower case. 


If only a: 


+ Destination variable is specified, the string is read from the destination, then 
is stored back to it. 


+ Source variable is specified, the string is read from the source, and the 
modified value is stored in the destination variable. In this case, the source 
variable remains unchanged. 


Windows application definition 


The example reads the user name from #1001 and copies it into ?Username. The 
StrLower command is then used to make sure the user name is all lower case. 
# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 
ReadText #1001 ?Username 
StrLower ?LowerCaseUsername $Username 


Type ?LowerCaseUsername #1002 
Click #1 


All 


3.0.4 or later 


Variable manipulator 

<Destination> 

The output variable. Also the input variable if no source is specified. 
[<Source>] 


The input variable. If not specified, Novell SecureLogin reads the destination 
variable, makes the necessary changes, and writes over the variable. 
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5.2.85 


Description 


Example 


Sub/EndSub 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Use the StrUpper command to modify a variable so that all the characters are 
upper case. 


If only a: 


+ Destination variable is specified, the string is read from the destination and is 
then stored back to it. 


+ Source variable is specified, the string is read from the source, and the 
modified value is stored in the destination variable. In this case, the source 
variable remains unchanged. 


Windows application definition 


This example reads the user name from #1001 and copies it into ?Username. The 
StrUpper command is then used to make sure the user name is all upper case. 
# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 
ReadText #1001 ?Username 
StrUpper ?UpperCaseUsername $Username 


Type ?UpperCaseUsername #1002 
Click #1 


Startup, Terminal Launcher, Web, or Windows 


3.5 or later 


Flow control 

Sub <Name> EndSub 

<Name> 

Any name entered to identify the subroutine. 


Use the Sub/EndSub commands around a block of lines within an application 
definition to denote a subroutine. 


You can also call a subroutine using the Call command. For more information, 
see Section 5.2.8, “Call,” on page 68. 
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5.2.86 


Example 


Submit 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Terminal Launcher application definition 


This example checks the emulator screen for the text Log On or Wrong Password. 
If either is found, the appropriate subroutine is called and run before the next part 
of the application definition. 


If -Text "Log On" 
Call "Log On" 
EndIf 
If -Text "Wrong Password" 
Call "WrongPassword" 
EndIf 
Sub Login 
Type $Username 
Type QE 
Type $Password 
Type QE 
EndSub 
Sub WrongPassword 
DisplayVariables "Enter correct password" 
$Password 
Call Login 
EndSub 


Web 


3.5 or later 


Action 
Submit 


None 
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Description 


Example 


Use the Submit command only in Web application definitions and only with 
Internet Explorer to allow for enhanced control of how and when a form is 
submitted. The Submit command performs a Submit on the form in which the first 
password field is found. The Submit command is ignored if used with Netscape. 


The function performed by the Submit command is automatically performed by 
Web application definitions by default. For example, the application definition: 


Type $Username 
Type $Password Password 
Types the user name and password and submits the form. 


When submits do not occur automatically However, submits do not occur 
automatically if any of the following commands are in the application definition: 
Type AN, Type \T, Submit, or Click. If any of these commands are used, you must 
use the Submit command or some other means to submit the form. 


Furthermore, an automatic submit does not occur if you type text into a specific 
text entry field. For example, in the application definition snippet below, the 
Submit command must follow the Type command for the application definition to 
work properly: 


Type $Username #1001 
Submit 
Web application definition 


This example enters the user name and password and then executes a manual 
Submit. 


Type $Username #1 
Type $Password #2 


Submit 
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5.2.88 


Substr 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Example 


Subtract 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Startup, Terminal Launcher, Web, or Windows 


7.0.3 or later 


Action 

SubStr [<var result>] [<var source>] [<var start>] [<var count>] 
<var result> 

The <var result> argument is the variable where the sub text is stored. 
<var source> 

The <var source> argument is the actual string. 

<var start> 

The <var start> argument is the index number of the sub text. 


<var count> 


The <var count> argument is the number of characters from the index number. 


Windows application definition 
This example displays a subtext from the given string. 


Substr ?result abc123ABC!@# 3 6 
?result 123ABC 


Startup, Terminal Launcher, Web, or Windows 


3.0 or later 


Variable manipulator 


Subtract <Start-Value> <Subtract-Value> [?Result] 
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Arguments 


Description 


Syntax examples: 


Example 


<Start-Value> 


The <Start-Value> argument is the start number from which the second argument 
is subtracted. This argument contains the result if the optional [?Result] argument 
is not passed in. If used: 


+ Without the [?Result] argument, then <Start-Value> must be a Novell 
SecureLogin variable, for example, ?StartValue or $StartValue. 


+ With the [?Result] argument, then <Start-Value> can be a Novell 
SecureLogin variable or a numeric value. 


<Subtract-Value> 


The <Subtract-Value> argument is the number subtracted from the first argument. 
<Subtract-Value> can be a Novell SecureLogin variable or a numeric value. 


[?Result] 


The result of the equation. This argument is optional but, if used, set to <Start- 
Value> - <Subtract-Value>. The [?Result] must be a Novell SecureLogin variable, 
for example, $Result or ?Result. 


Use the Subtract command to subtract one value from another. 


This is useful if you are implementing periodic password change functionality for 
an application. You can use the Subtract command (in conjunction with the 
Divide function and the Slina DLL) to determine the number of days that have 
elapsed since the last password change. Other numeric commands include the 
Add, Divide, and Multiply. 


For more information see: 


+ Section 5.2.2, “Add,” on page 62 
+ Section 5.2.21, “Divide,” on page 84 
+ Section 5.2.54, “Multiply,” on page 118 


NOTE: The Subtract command correctly subtracts when <Start-Value>, 
<Subtract-Value> and <Result-Value> are between -2147483648 and 
+2147483647. 


Subtract "1" "2" ?Result 

Subtract ?LoginAttempts ?LoginFailures 
Subtract ?LoginAttempts ?LoginFailures ?Result 
Subtract ?LoginAttempts "3" 

Subtract ?LoginAttempts "3" ?Result 


Windows application definition 


This example reads the values of control IDs 103 and 104 into variables. From 
there they are subtracted and typed into control ID 1. 


ReadText #103 2Number1 

ReadText #104 ?Number2 

Subtract ?Number1 ?Number2 ?Result 
Type ?Result 
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5.2.90 


Tag/EndTag 


Use with 


Novell SecureLogin 
version 


Type 


Usage 


Arguments 
Description 


Example 


TextInput 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Description 


Advanced Web application definitions 


3.5 or later 


Tag specifier 

Tag 

EndTag 

None 

Use the Tag/EndTag commands to find HTML tags. 

This example finds the form that has an attribute of Name with a value of Log on. 
Tag "Form" 


Attribute "Name" 
"Log on"EndTag 


Advanced Web application definitions created using the Web Wizard. 


3.5.x or later 


Action 
TextInput #FormID:FieldID -value "value" 
#FormID:FieldID 


The ID that was given to the matched field in the Site block using MatchField 
command. The FormID and FieldID must be unsigned integers. 


-value "value" 
The text value to be input. 
Use the TextInput command after a Site block to input text into a specified field. 


You can enter text into fields of type password/text/textarea/file. 
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5.2.91 


Example 


Title 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


In this example the text value of the system user name and password are passed to 
the application definition. 


# === Logon Application Definition #2 == 
# === Google Initial Logon ==== 
1 כ‎ = - 2 e 


Site Login -userid “Google Log On” -initial 
MatchDomain “www.google.com” 

MatchField #1:1 -name “Email” -type “text” 
MatchField #1:2 -name “Passwd” -type “password” 
MatchField #1:3 -name “Cookie” -type “check” 
EndSite 

SetPrompt “Enter your user credentials” 
TextInput #1:1 -value “$Username” 

TextInput #1:2 -value “$Password” 
FocusInput+1:2 -focus “true” 

BooleanInput +1:3 -check “false” 

PressInput 

Endscript 


Java, Windows 


3.5 or later 


Dialog specifier 

Title <Window-Title> [-regex “regular expression”] 
<Window-Title> 

The text to test against the window title. 

-regex 


You may also use regular expressions to match part of a URL, such as the domain 
only. 


For more information regarding regular expressions see: 


www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html (http:// 
www.boost.org/doc/libs/1_33_1/libs/regex/doc/syntax_perl.html) 
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Description 


Example 1 


Example 2 


Type 


Use with 


Novell SecureLogin 
version 


Use the Title command to retrieve the title of a window and compare it against 
the string specified in the <Window-Title> argument. For this block of the 
application definition to run, the retrieved window title and the <Window-Title> 
argument must match the text supplied to the Title command in the dialog block. 


Title is one of the main commands to identify a window. However, the Title 
command alone may not be enough - if there is more than one window in a 
platform (application) with the specified title, the Novell SecureLogin application 
definition will run every time that window is detected. 


Make Title the first command in the Dialog block to speed the matching process 
and ensure that all detected controls are also created. However, with some 
applications, if the text to match is too long, this will slow the detection and creation 
process. Consequently, if your application definition is unusually slow to execute, 
try placing the Title command after all other commands in the Dialog block. 


For Windows applications, either Title or Class should be defined in a Dialog block 
at least once. 


Uniquely identifying a window To uniquely identify a window, the Title 
command is typically used with the Class or Ctrl commands. For more information, 
see Section 5.2.10, “Class,” on page 70 and Section 5.2.15, “Ctrl,” on page 78. 


NOTE: Use the Novell Window Finder tool to determine the window title. 
Windows application definition 


This example tests the dialog box to see if it has the correct title. If the title is not 
correct, the application definition passes on to the next Dialog block. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Logon" 
EndDialog 


Type $Username #1001 
Type $Password #1002 
Click #1 


Windows application definition 
This example uses a regular expression to identify the window title. 


Dialog 
Title "Logon - Simple" 
Class "#32770" 
Parent 
Class "#32770" 
Title -regex "training" 
EndParent 
Ctrl #1001 
Ctrl #1002 
Ctrl #1 
EndDialog 


Java, Terminal Launcher, Web, or Windows 


3.5 or later 
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Type 
Terminal usage 


Windows usage 


Web usage 


Arguments 


Action 

Type [-Raw] <Text> 

Type <Text> [<#Ctrl-ID>] 

Type [-Raw] <Text> 

Type [-order] <Text> [<#Order-ID>] 
Type [-msg] <Text> [<#Ctrl-ID>] 
Type <Text> [<#Field-ID>] 

Type <Text> ["password"] 

Type [-Raw] <Text> 

[-Raw] 


By default, when typing into a terminal emulator or Windows application, Novell 
SecureLogin verifies that the window exists before continuing. This verification 
process is disabled when the -Raw argument is provided. Furthermore, instead of 
setting the text in the field directly, the -Raw argument simulates actual keystrokes, 
causing Novell SecureLogin to type into whichever window has focus.The -Raw 
argument can also be used in a Web application. The -Raw argument attempts to 
type the text into the window that owns the Web page (Internet Explorer or Firefox) 
and works the same as -Raw on Windows applications. 


[-order] 


If the control ID's are not constant, utilize the -order argument to instruct Novell 
SecureLogin to type into a control based on the creation order and not the tab 
order. For more information on the -order argument usage, see “Example 5” on 
page 168. 


[-msg] 


The -msg argument can be used when a Type command is sending the data 
correctly, but the application is not successfully reading the data. The -msg 
argument will only work in Windows applications as the argument simulates the 
keys being pressed (that is, key down, character, key up). For Web applications use 
the -Raw argument to get the JavaScript to trigger. The -msg argument sends the 
data character by character versus sending the text string all at once. This -msg 
option is often useful for older Windows applications, particularly old versions of 
Lotus Notes. 


<Text> 


The text to type into this area. This text can be static text, such as ABC, or any 
Novell SecureLogin variable, such as $Username. 


[<#Ctrl-ID>] 


For Windows application definitions, this optional argument specifies the control 
into which to type the text. Use the Novell Window Finder to extract these control 
IDs. For more information, see “Windows specific” on page 167. 


[<#Order-ID>] 


For Windows application definitions, this parameter specifies which control based 
on the creation order in which to type the text. 
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Description 


Example 1 


[<#Field-ID>] 


For Web application definitions, this optional argument specifies the text field into 
which to type the text. For more information, see “Web specific” on page 167. 


[password] 


For Web application definitions, this optional argument specifies to perform this 
type into the password field on this form. If [password] is used, that application's 
application definition cannot use a <#Ctrl-ID> argument. For more information, see 
“Web specific” on page 167. 


Use the Type command to enter data such as user names and passwords into 
applications. There are reserved character sequences that are used to type special 
characters, for example Tab and Enter. If it is not possible to determine control IDs 
in a Windows application, and the Type command is not working, use the SendKey 
command instead. 


Windows specific In Windows, if the <#Ctrl-ID> argument is: 


+ Provided, it must be a number that refers to a control ID as identified by the 
Window Finder Tool. Novell SecureLogin will then send the contents of the 
<Text> argument directly to the window and to the specific control that 
matches the <#Ctrl-ID> argument. 


+ Not specified, Novell SecureLogin will send keystrokes to whichever control 
has focus. In the Windows environment, the -Raw option is often useful when 
the Window Finder Tool is unable to determine control IDs for the text entry 
areas of an application, or these control IDs are changing. If using the -Raw 
option, then you cannot use the <#Ctrl-ID> argument. 


Web specific For Web pages, there are two ways to specify which field receives 
<Text>. 


+ The first method uses absolute positioning by means of the <#Field-ID> 
argument. The <#Field-ID> is a number that refers to the location of the field 
within the HTML form. For example, #1 refers to the first text entry field in the 
Web form; #2 refers to the second text entry field, and so on. 


+ The second method uses relative positioning using the password argument. In 
this method the Novell SecureLogin agent first locates the text field within the 
HTML form that is a password field, and types <Text> into that field. Other 
type commands send their <Text> parameters to fields that are relative to the 
first password field. 


For example, the Type command immediately preceding the Type command 
that has the [Password] argument is sent to the text field immediately 
preceding the first password field. 


Windows application definition 


This example typifies the use of the Type command in a Windows application 
definition. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


Type $Username #1001 
Type $Password #1002 
Type "DB2" #1003 
Click #1 
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Example 2 


Example 3 


Example 4 


Example 5 


Windows application definition 


This example shows the use of the -Raw switch. This switch is not actually required 
in this instance, and is only used as an example. 


# Calculator Is Active 
Dialog 
Class #SciCalc 
Title "Calculator" 
EndDialog 
Type -Raw "15" 
Type -Raw "+" 
Type -Raw "20" 
Type -Raw "=" 


Windows application definition 


This example shows the use of the -msg switch. In this instance the switch is not 
actually required and is only used as an example of the use of Password as the - 
msg argument. 
# Calculator Is Active 
Dialog 
Class #SciCalc 
Title "Calculator" 
EndDialog 
Type -msg $Password #480". 
Windows application definition 


The following syntax examples compare and contrast the use of the various Type 
command arguments. 


Type +1 "text" 

Will type text into control with ID of 1 

Type +1 "text" -order 

Will type text into the first control found in the dialog when enumerating the children. 
Type +1 "text" -msg 


Will type text into the first control with an ID of 1 it finds within the set of windows 
allowing some time for the control to be created. 


Type +1 "text" -raw 
Type +1 "text" -focus 


Ignores the unused parameter #1 
Windows application definition 


This example shows the use of the -order switch and demonstrates the possible 
“order” of the parameter. 


Type -order #1 "some text" 
Type #2 "some text" -order 
Type "some text" -order #3 
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Example 6 Web application definition 


This example uses the Novell SecureLogin agent to automatically generate this 
application definition for the mail.yahoo.com site. This example shows the use of 
password as the [<Field Name>] argument. 


Type $Username 
Type $Password Password 


In the application definition above, the Novell SecureLogin agent locates the first 
password field. The first Type command sends $Username to the field immediately 
before the password field. The second Type command sends $Password to the 
password field. The same application definition could be rewritten using absolute 
placement as shown below. In the following example, the Submit command is also 
used to automatically submit the page. 


Type $Username #1 
Type $Password #2 
Submit 


Sending keyboard commands using Type 


Novell SecureLogin can send special keyboard keystrokes to Windows and Web-based applications 
to emulate the user's keyboard entry. The Type command can pass keystrokes through to the window 
that the application definition is working. These special commands include the ability to select menu 
items, send Alt, and send other keyboard combinations. 


Special key commands 


Type Simulates 

\Alt+<key> Pressing the ALT key plus the desired <key>. 
IShift+<key> Pressing the SHIFT key plus the desired <key>. 
\Ctrl+<key> Pressing the CTRL key plus the desired <key>. 
\LWin+<key> Pressing the left Windows key plus the desired <key>. 
\RWin+<key> Pressing the right Windows key plus the desired <key>. 
\Apps+<key> Pressing the Application key plus the desired <key>. 


Raw key commands 


You can also use the Type command to send a combination of raw key commands. Section 7.1, 
“Windows Keyboard Functions,” on page 179 details the available keyboard sequences you can use 
with the Type command. 


Type Simulates 


\|<xxx> The format for sending a raw key command, where <xxx> represents the 
keyboard code. 


\|18+65 Pressing the ALT-A keys in sequence. 
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Type commands used with Terminal Launcher 


Terminal Launcher uses the High Level Language Application Programming Interface (HLLAPI) to 
interface with a wide range of mainframe emulators that implement this programming standard. 
Listed below are the @ commands that you can use in the Type command. These commands perform 
specific emulator and mainframe functions. For example, you can send an Enter, Tab, cursor key, 
issue a mainframe emulator print screen, or reset function. 


The @ commands are used in application definition language in the following format: 


+ TYPE E command 
+ WAITFORTEXT "Log on:" 


+ Type $username 


4 


Type OT 
+ Type $password 
+ Type @E 


The Section 7.1, “Windows Keyboard Functions,” on page 179 details the commands that you can use 
within a Terminal Emulator application definition. 


WaitForFocus 


Use with Windows 


Novell SecureLogin 3.5 or later 


version 
Type Flow control 
Usage WaitForFocus <#Ctrl-ID> [<Repeat-Loops>] 
Arguments <#Ctrl-ID> 
The ID number of the control with the focus. 
[<Repeat-Loops>] 
The number of repeat-loops that will run. 
Description Use the WaitForFocus command to suspend the running of the application 


definition until the <#Ctrl-ID> has received keyboard focus, or the <Repeat-Loops> 
expire. The <Repeat-Loops> is an optional value that defines the number of loop 
cycles to run. The <Repeat-Loops> value defaults to 3000 loops if nothing is set. 
Once focus is received, the application definition continues. 


Set the figure to a negative number (for example, WaitForFocus "#1065" "-1") for 
the <Repeat-Loops> never to expire. If the <Repeat-Loops> is set to O (zero), it 
loops until the window defined in the Dialog/ EndDialog statement is given 
keyboard focus. 


NOTE: Do not place WaitForFocus commands within Dialog / EndDialog 
statements. 


Syntax examples WaitForFocus #301 
WaitForFocus #301 "2000" 
WaitForFocus #301 "0" 
WaitForFocus #301 "-1" 
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5.2.94 


Example 1 


Example 2 


WaitForText 


Use with 


Novell SecureLogin 
version 


Type 
Usage 


Arguments 


Windows application definition 


This example has Novell SecureLogin waiting indefinitely for window 301 to get 
focus. Once the login dialog box is detected, it enters the user credentials. 


# Logon Dialog Box 
Dialog 
Class #32770 
Title "Log on" 
EndDialog 


WaitForFocus #301 "-1" 
Type $Username 

Type \T 

Type $Password 

Type \N 


This example has the WaitForFocus command suspend the running of the appli- 
cation definition until control ID #15 is reached and a message box with “love” 
should appear. 


## BeginSection: "Logon Window" 

Dialog 

Class "Notepad" 

Title "Untitled - Notepad" 

EndDialog 

Setprompt "Optional:" 

# Here the correct ID with the loops set to 0 
WaitForFocus #15 0 

Set ?thu "love\me" 

RegSplit "(.*)\\(.*)" ?thu ?Domain ?User 
MessageBox ?Domain 

## EndSection: "Logon Window" 


Terminal Launcher 


3.5 or later 


Flow control 
WaitForText <Text> 
<Text> 


The text for which the application definition is waiting. 
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Description 


Example 


Use the WaitForText command to make the Terminal Launcher wait for the 
specified text to display before continuing. For example, you may make Novell 
SecureLogin wait for a user name field to display before attempting to type a user 
name. 


The text may appear anywhere on the terminal screen and is usually case 
sensitive (this depends on the Terminal Emulator itself). If the text is written in the 
wrong case, the terminal launcher will pause and try to find the correct text in the 
correct case, until the terminal screen times out. 


WaitForText is not working, try leaving the initial letter off the <Text> to avoid‏ זו 
any conflict with case sensitivity. For example, WaitForText logon will work‏ 
regardless of whether the text ‘log on’ is presented on the terminal screen as Log‏ 
on or log on. However, WaitForText "Log on" will only work if the word log on is‏ 
presented on the screen as ‘Log on’.‏ 


Also, some terminal emulators will not correctly match text that is hard against the 
left margin of the window. Again, if you encounter this situation, try to match text 
without the leading character. 


Terminal Launcher application definition 


This command instructs Novell SecureLogin to wait for the text ogin: to appear on 
the emulator screen before entering the user name. It will then wait for assword: to 
display before entering the password. 


WaitForText "ogin:" 
Type $Username 

Type @E 

WaitForText "assword:" 
Type $Password 

Type @E 


Novell SecureLogin Application Definition Guide 


6.1 


6.1.1 


Testing Application Definitions 


* Section 6.1, “Using the Novell SecureLogin Test Application,” on page 173 


Using the Novell SecureLogin Test Application 


To allow Administrators and other application definition writers to practice their application 


definition creation skills, the Password Test application is included in the software package. It is 


designed to replicate an application logon panel and supports the following processes: 


+ Initial log in 
+ Wrong password 


¢ Password change 


If you do not have the test application, contact Novell Technical Support. 


The following example, application definition for the Password Test application, further explains the 


SecureLogin application definition principles. 


Example Application Definition for the Test Application 


The application definition for the PSL Password Test Application (PasswordTest . exe) provides an 


example of a typical Windows application definition, including error handling and changing the 


password. Remember, the password for this application is hard-coded to single when the application 
is closed and restarted. This can cause confusion when setting strong password policies and 
changing passwords. You must also create a password policy called PwdTestPolicy, according to the 
password policy defined in this application definition. The password policy must require a minimum 
of 6 characters, but no complex rules, in order to use single as a password. 


Here is the sample application definition in its entirety. Following this application definition is the 
explanation of what each section does. 


# Set Password Policy 


RestrictVariable $Password PwdTestPolicy 
# ==== BeginSection: Log on ==== 


Dialog 
Class "#32770" 
Ctrl #1001 


Title "Log on" 


EndDialog 

SetPrompt "Username =====>" 
Type $Username #1001 
SetPrompt "Password =====>" 


Type $Password #1002 
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SetPrompt "Domain =====>" 
Type $Domain #1003 
Click #1 
SetPrompt "Please enter your user name and password to access Password Test. 
SecureLogin will remember and automatically log you on in future. IT Help Desk 
x4532" 

==== EndSection: Log on ==== 


==== BeginSection: Log on failure ==== 
Dialog 


Class "#32770" 
Title "Log on failure" 
EndDialog 


# Read the error message and set it as a temporary variable, then clear it 
ReadText #65535 ?ErrorMessage 
Click #2 


# If log on failed, display the current stored Username and Password and prompt the 
user to verify them, then retry log on 
If "You have failed to log on." -In ?ErrorMessage 

DisplayVariables "Log on to Password Test failed. The password for this 
application must be single when it first starts. IT Help Desk x4532" 
# Press Alt>F and L to invoke the logon box so the user doesn't have to. 


Type -Raw "MA1t+F" 
Type -Raw "L" 
Type $Username 
Type $Password 
Type $Domain 
EndIf 
# ==== EndSection: Log on ==== 


# ==== Begin Section: Change Password ==== 
# Change Password Dialog Box 

Dialog 

Class "#32770" 

Title "Change Password" 

EndDialog 


# Backup password, fill in the old user name and password, then start the change 
password routine 

Set ?PwdBackup $Password 

Type $Username #1015 

Type $Password #1004 

ChangePassword ?NewPwd "Please enter a new password for this application." 

Type ?NewPwd #1005 

Type ?NewPwd #1006 

Click #1 


# Change password successful message 
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Dialog 
Class "#32770" 
Ctrl #65535 "You have changed your password successfully." 


Title "Change successful" 


EndDialog 

# Clear application owned message and accept new password 
Click #2 

Set $Password ?NewPwd 

# ==== End Section: Change Password ==== 


Application Definition Explained 


You can use the same application definition to show what function each section performs. Dialog/ 
EndDialog blocks define a Windows dialog box. When the dialog box appears, SecureLogin detects 
that this dialog box is based on the information found within the dialog block. The Dialog/ 
EndDialog block must contain enough information for the block to be unique, or the application 
definition runs when other dialog boxes owned by the same executable with the same information 
appear. 


When SecureLogin detects that all the information between Dialog and EndDialog is contained in 
the dialog box on the screen (for example, the application login box, the change password box, or the 
failed logon box), it runs the application definition commands until it sees the next dialog statement 
or the end of the application definition, whichever is applicable. The order does not matter in 
Windows application definitions, because SecureLogin watches for all dialog boxes while the 
executable is running. Use a logical order for troubleshooting purposes. 


Dialog boxes 


The following application definition example shows screen captures of the relevant dialog boxes. You 
can use the Window Finder tool to gather information about the title of the window, class names, 
dialog IDs, and so on. Use the wizard to automate the application definition creation. 


Application definition section Comments 

# Set Password PolicyRestrictVariable This restricts the $Password variable to comply 
$Password PwdTestPolicy with the Password Policy "PwdTestPolicy”. 

# ==== BeginSection: Log on ====Dialog When PasswordTest.exe runs, SecureLogin 
Class "#32770" Ctrl #1001 Title "Log watches for dialog boxes that appear and match 
on"EndDialog the information defined between the Dialog/ 


EndDialog commands. 


You can specify all values, or a few, as long as 
the information specified is unique to that dialog 
box. 
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Application definition section Comments 


SetPrompt "Username =====> Type the stored ($) Username variable into 
"Type $Username #1001 #1001, and so on. SetPrompt is used to 
Pee ee אוש‎ customize the window the user sees when there 
SetPrompt "Domain =====>" are no credentials stored. 

E en #1003 When the user first runs an application that is 
SetPrompt "Please enter your Username newly enabled for single sign-on, SecureLogin 
and prompts for their login credentials, and stores 


Password to access NSL Test. SecureLogin and remembers them for future login attempts. 
will remember and automatically log you 

on in future. IT Helpdesk x4546" 

# ==== EndSection: Log on ==== 


CN [The title is Log In. 
The Class is #32770. 


2- €) SecureLogin 


The Username field is Control ID #1001. 


The Password field is Control ID #1002. 


The Other field is Control ID #1003. 


The OK button is Control ID #1. 


g log Do's a yed eime 
the application definition is run by a user. It 
Please enter your Username and Password to access NSL Test. prompts the user to enter credentials for 
SecureLagin will remember and automatically log you on in future. IT 8 
YP 4546 SecureLogin to store. 


The SetPrompt command is used throughout 


Usemame ------ > ] the example application. 


xi This is the login failure dialog box. 


You have Failed to login. The title is Login Failure. 
The class is #32770. 


The OK button is Control ID #2. 


The error message is Control ID #65535 
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Application definition section Comments 


This is the Change Password dialog box. 
Change Password 


The Username field is Control ID #1015. 
Username: 


| The Old Password field is Control ID ++1004. 


Old Password: The New Password field is Control ID ++1005. 


pa 


The Confirm New Password field is Control ID 
New Password: #1006. 


pees ——_—_—_——— 


Confirm New Password: 


e 
1 | Cancel | 


The OK button is Control ID #1. 


5 E The ChangePassword command is used in the 
example application definition to display a dialog 


r Enter New Password box for the user to enter a new password. 


Please enter your new password for the password test The dialog box is customized to provide more 
application. IT x4546 information for the user. 


New Password: | 
Confirm Password: | 


coca] 
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1.1 


Reference Commands and Keys 


¢ Section 7.1, “Windows Keyboard Functions,” on page 179 


* Section 7.2, “Terminal Emulator Commands,” on page 184 


Windows Keyboard Functions 


The following reference tables list the Windows keyboard functions. You can use these functions in 
conjunction with the Type command by referencing the appropriate keyboard code. 


Do not type quotation marks before and after the keys. In this case the keys are taken literally, as 
shown in the following table. 


Table 7-1 Typing Keys 


For this command 
Alt+Print Screen 
Shift+Home 


Shift+End 


Type 
\Alt+\|44 
\Shift+\|36 
\Shift+\|35 


For more information about the Type command, see Section 5.2.92, “Type,” on page 165. 


Table 7-2 Windows Keyboard Functions 


Function 

Left mouse button 
Right mouse button 
CTRL-Break 

Middle mouse button 
X1 mouse button 

X2 mouse button 
Backspace 

Tab 

Clear 


Enter 


Decimal Comment 


12 5 on the keypad 
13 
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Function Decimal Comment 


Shift 16 
Ctrl 17 
Alt 18 
Pause 19 
Cap Lock 20 
Escape 27 
Space 32 
PageUp 33 
PageDown 34 
End 35 
Home 36 
Left-arrow 37 
Up-arrow 38 
Right-arrow 39 
Down 40 
Select 41 
Execute 43 
Print 44 
Insert 45 
Delete 46 
Help Key 47 
0 48 
1 49 
2 50 
3 51 
4 52 
5 53 
6 54 
7 55 
8 56 
9 57 
A 65 
B 66 
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Function Decimal Comment 


67 
68 
69 
70 
71 


I © nn mMm U QO 


72 


l 73 


J 74 


K 75 


- 


76 


77 


78 


79 


80 


81 


82 


83 


84 


85 


86 


87 


88 


89 


.o voz =z‏ 46 ₪ 6 ₪ > < א 


90 
Left Windows Key 91 
Right Windows Key 92 
Application Key 93 
Sleep Key 94 
Keypad 0 96 
Keypad 1 97 
Keypad 2 98 
Keypad 3 99 
Keypad 4 100 
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Function Decimal Comment 


Keypad 5 101 
Keypad 6 102 
Keypad 7 103 
Keypad 8 104 
Keypad 9 105 
Keypad asterisk (*) 106 
Keypad plus sign (+) 107 
Keypad separator 108 
Keypad minus sign (-) 109 
Keypad period (.) 110 
Keypad slash mark (/) 111 
F1 key 112 
F2 key 113 
F3 key 114 
F4 key 115 
F5 key 116 
F6 key 117 
F7 key 118 
F8 key 119 
F9 key 120 
F10 key 121 
F11 key 122 
F12 key 123 
F13 key 124 
F14 key 125 
F15 key 126 
F16 key 127 
F17 key 128 
F18 key 129 
F19 key 130 
F20 key 131 
F21 key 132 
F22 key 133 
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Function 


F23 key 

F24 key 

Num Lock key 

Scroll Lock 

Left Shift 

Right Shift 

Left Control 

Right Control 

Left Menu 

Right Menu 

Browser Back key 
Browser Forward key 
Browser Refresh key 
Browser Stop key 
Browser Search key 
Browser Favorites key 
Browser Start and Home key 
Volume Mute key 
Volume Down key 
Volume Up key 

CD Next Track key 
CD Previous Track key 
CD Stop Media key 
CD Play/Pause key 
Launch Mail key 
Media Select key 
Start Application 1 key 


Start Application 2 key 


Decimal 


134 
135 
144 
145 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
186 
187 
188 
189 
190 


Comment 


Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Applies to Windows 2000 + 
Semi Colon/Colon 
Equals/Plus Key 
Comma/Less Than 
Minus/Underscore 


Period/Greater Than 
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Function 


/ 


Play Key 


Zoom Key 


Decimal 


191 


192 


219 


220 


221 


222 


250 


251 


7.2 Terminal Emulator Commands 


Comment 


Slash/Question Mark 

Single Open Quote/Tilde 
Left Square/Curley Bracket 
Back slash/Pipe 

Right Square/Curley Bracket 


Single Close Quote Double 
Quote 


The following table lists the terminal commands in terminal emulator application definitions. 


The Type Command 
@B 
ec 
@D 
@E 
@F 
@H 
Ol 
₪1 
@L 
@N 


@O 
@P 
@R 
@T 
@U 
@V 
@X* 
@Y 
@Z 


Meaning 

Left Tab 

Clear 

Delete 

Enter 

Erase EOF 

Help 

Insert 

Jump (Set Focus) 
Cursor Left 


New Line 


Space 

Print 

Reset 

Right Tab 

Cursor Up 

Cursor Down 

DBCS (Reserved) 
Caps Lock (No action) 


Cursor Right 
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The Type Command 


@A@C 
@A@D 
@A@E 
@A@F 
@A@H 
@A@I 

@A@J 

@A@L 
@A@Q 
@A@R 


@A@T 
@A@U 
@A@V 
@A@Z 
@A@9 
@A@b 
@A@c 
@A@d 
@A@e 


Meaning 

Test 

Word Delete 
Field Exit 

Erase Input 
System Request 
Insert Toggle 
Cursor Select 
Cursor Left Fast 
Attention 


Device Cancel (Cancels 
Print Presentation 
Space) 


Print Presentation Space 
Cursor Up Fast 

Cursor Down Fast 
Cursor Right Fast 
Reverse Video 
Underscore 

Reset Reverse Video 
Red 

Pink 


The Type Command 
@0 
@1 
@2 
@3 
@4 
@5 
@6 


@7 
@8 


Meaning 
Home 
PF1/F1 
PF2/F2 
PF3/F3 
PF4/F4 
PF5/F5 
PF6/F6 


PF7/F7 
PF8/F8 
PF9/F9 
PF10/F10 
PF11/F11 
PF12/F12 
PF13 


PF14 
PF15 
PF16 
PF17 
PF18 
PF19 
PF20 
PF21 
PF22 
PF23 
PF24 
End 


ScrLk (No action) 


Num Lock (No action) 


Page Up 
Page Down 
PA1 

PA2 


The Type Command 
@A@f 

@A@g 

@A@h 

@A@i 

@A@I 

@AQj 

@A@t 


@A@y 
@A@z 
@A@ 

@A@< 
@A@ 

@S@x 
@S@E 


@S@y 
@xX@c 
@X@7 
@X@6 
@xX@5 
@X@1 
@M@O0 
@M@1 
@M@2 
@m@3 
@M@4 
@M@5 
@M@6 
@M@7 
@M@8 
@M@9 
@M@- 

@M@, 


Meaning 

Green 

Yellow 

Blue 

Turquoise 

Reset Host Colors 
White 


Print (Personal 
Computer) 


Forward Word Tab 
Backward Word Tab 
- Field - 

Record Backspace 
+ Field + 

Dup 


Print Presentation Space 
or Host 


Field Mark 

Split Vertical Bar (i) 
Forward Character 
Display Attribute 
Generate SO/SI 
Display SO/SI 

VT Numeric Pad 0 
VT Numeric Pad 1 
VT Numeric Pad 2 
VT Numeric Pad 3 
VT Numeric Pad 4 
VT Numeric Pad 5 
VT Numeric Pad 6 
VT Numeric Pad 7 
VT Numeric Pad 8 
VT Numeric Pad 9 
VT Numeric Pad 


VT Numeric Pad 


Reference Commands and Keys 


185 


186 


The Type Command 
@z 

@M@h 
@M@N 
@M@M 
@M@L 
@M@K 
@M@J 
OMOI 
@M@H 
@M@G 
@M@F 
@M@(space) 
@M@E 
@M@D 
@M@C 
@M@B 
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Meaning 

PA3 

VT Hold Screen 
Control Code SO 
Control Code CR 
Control Code FF 
Control Code VT 
Control Code LF 
Control Code HT 
Control Code BS 
Control Code BEL 
Control Code ACK 
Control Code NUL 
Control Code ENQ 
Control Code EOT 
Control Code ETX 


Control Code STX 


The Type Command 
@M@. 
@M@e 
OMOf 
@M@i 
זו‎ 
@M@s 
@M@p 
@M@n 
@M@a 
@M@b 
@M@c 
@M@d 
@M@O 
@M@Q 
@M@P 
@M@A 


Meaning 

VT Numeric Pad 

VT Numeric Pad Enter 
VT Edit Find 

VT Edit Insert 

VT Edit Remove 

VT Edit Select 

VT Edit Previous Screen 
VT Edit Next Screen 
VT PF1 

VT PF2 

VT PF3 

VT PF4 

ControlCode S1 
ControlCode DC1 
ControlCode DLE 


ControlCode SOH 


8.1 


8.2 


Application Definition Commands for 
SNMP Alerts 


Novell SecureLogin produces Simple Network Management Protocol (SNMP) for network 
monitoring software to trap. A simple application definition command is used to send the alerts. 


You might need to copy the LIBSNMP.DLL file to the Windows\System32 directory for SNMP support 
to work. 


Creating an SNMP Alert 


In order to produce an SNMP alert, place the following command in the application definition where 
you would like to create the alert: 


NOTE: You may have to copy the LIBSNMP.DLL file to the Windows \ System32 directory for SNMP 
support to work. 


Run C:\Progra~i\Novell\Secure~1\Slsnmp.exe <Community Name> 
<Host IP Address> <Text> 


Where: 


<Community Name> is the case-sensitive community name to which this computer sends trap 
messages. 


<Host IP Address> is the IP address of the SNMP host. 


<Text> is the text displayed as the message at the host. 


Example 


The following is an example application definition: 


Dialo 
Class #32770 
Title "Incorrect Password" 
EndDialog 
Run ..\Slsnmp.exeame> SNMPCOmmunity1 192.168.156.23 
"PSL - Incorrect password in finance system." 
MessageBox "You have entered an incorrect password. The 
administrator has been notified. Please restart the application 
and try again." 
KillApp "PasswordText.exe" 
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